{"id":19534729,"url":"https://github.com/insighio/microfreezer","last_synced_at":"2025-08-03T03:38:07.116Z","repository":{"id":37815541,"uuid":"354874120","full_name":"insighio/microfreezer","owner":"insighio","description":"A software/firmware update packager for micropython platforms bypassing 'frozen' frolder restrictions","archived":false,"fork":false,"pushed_at":"2024-03-01T08:38:21.000Z","size":67,"stargazers_count":11,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-26T14:42:23.334Z","etag":null,"topics":["esp32","esp8266","firmware","frozen","micropython","ota","package","pycom"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/insighio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-04-05T15:06:00.000Z","updated_at":"2025-02-26T14:20:30.000Z","dependencies_parsed_at":"2024-03-01T09:49:12.503Z","dependency_job_id":null,"html_url":"https://github.com/insighio/microfreezer","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/insighio/microfreezer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insighio%2Fmicrofreezer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insighio%2Fmicrofreezer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insighio%2Fmicrofreezer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insighio%2Fmicrofreezer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/insighio","download_url":"https://codeload.github.com/insighio/microfreezer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/insighio%2Fmicrofreezer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268491312,"owners_count":24258726,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-03T02:00:12.545Z","response_time":2577,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp32","esp8266","firmware","frozen","micropython","ota","package","pycom"],"created_at":"2024-11-11T02:15:24.698Z","updated_at":"2025-08-03T03:38:07.022Z","avatar_url":"https://github.com/insighio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# microfreezer\n\nmicrofreezer is a handy tool providing an alternative update method for micropython-enabled microcontrollers, by packaging a project into either an update package or into the 'frozen' part of the firmware regardless the included file types.\n\n![microfreezer-scheme-4](https://user-images.githubusercontent.com/550020/114547587-48178e80-9c67-11eb-8c41-c2050f63ca33.png)\n\n# Method 1: freezing the unfreezable\n\nHaving the source code of the micropython firmware, any Python source code added in `esp32/frozen` will be compiled and added with the firmware. In the case of Pycom devices, that folder is at `pycom-micropython-sigfox/esp32/frozen` and includes multiple other folders with necessary code. The suggested folder for placing custom Python files is `pycom-micropython-sigfox/esp32/frozen/Custom/`. More info on this can be found here: https://docs.pycom.io/advance/frozen/\n\nConsider having the following project folder that needs to be flashed into multiple microcontrollers.\n\n```\n|- .git\n|- lib\n|  |- lib_a.py\n|  |- README.md\n|- html\n|  |- index.html\n|  |- favicon.ico\n|- main.py\n|- boot.py\n|- README\n|- LICENSE\n```\n\n## prepare the configuration file\n\nmicrofreezer provides an alternative way of packing these files into the firmware. First of, prepare the configuration file by defining the following keys:\n\n1. `excludeList`: select irrelevant files that should be ignored. (if not provided, all files will be included)\n    * \"README.md\", \"README\", \"LICENSE\", \".git\" files\n1. `directoriesKeptInFrozen`: first select which folders of the project will be added in the `frozen` modules to be used directly by the user code. (if not provided, no files will be kept in `frozen`)\n    * \"lib\" folder contents\n1. `enableZlibCompression`: by default is enabled. kept for cases of zlib unavailability. Turning it off results to bigger packages.\n1. `targetESP32`: flag to set the build configurations for ESP32 devices\n1. `targetPycom`: flag to set the build configurations for Pycom devices\n1. the rest of the files will be converted into a compressed format, packed into the `frozen` modules and will be ready to be exported to the user space \"ex. /flash or / paths\".\n1. `minify`: minify if possible the .py source files. requires _pip install python-minifier_\n\nPutting these into a configuration file named `config.json`:\n\n```json\n{\n  \"excludeList\": [\n             \"README\",\n             \"README.md\",\n             \"LICENSE\",\n             \".git\"],\n  \"directoriesKeptInFrozen\": [\"lib\"],\n  \"enableZlibCompression\": true,\n  \"flashRootFolder\": \"/\",\n  \"minify\": true,\n  \"minifyExcludeFolderList\": [\"~/path/to/folder/to/exclude/from/minify\"],\n  \"targetESP32\": true,\n  \"targetPycom\": false  \n}\n```\n\n## run microfreezer\n\nReady to run microfreezer. The `config.json` needs to be present at the same path as microfreezer. If not, default values will be used as indicated above.\n\n```bash\n#python3 microfreezer.py (-v: verbose output) \u003cproject-folder-path\u003e \u003coutput-folder-path\u003e\npython3 microfreezer.py ~/projects/my_new_project ~/projects/my_new_project_packed\n\n#or\n\npython3 microfreezer.py -s ~/projects/my_new_project -d ~/projects/my_new_project_packed\n```\n\nThe output is split into two folders `Base` and `Custom` based on the directory design of Pycom devices:\n\n```\n|- Base\n|  |- _main.py\n|- Custom\n|  |- lib_a.py\n|  |- _todefrost\n|  |  |- base64_0.py\n|  |  |- base64_1.py\n|  |  |- base64_2.py\n|  |  |- base64_3.py\n|  |  |- microwave.py\n|  |  |- package_md5sum.py\n```\n\nCopy both folders to `pycom-micropython-sigfox/esp32/frozen` folder and rebuild firmware. Now it is ready to be flashed.\n\nDuring the boot of the device:\n* _main.py checks if md5sum of the files in \"_todefrost\" path has changed\n* if yes, runs \"microwave\" module that reads each file in \"_todefrost\" and unpacks each file to the desired destination in user space (ex. /flash)\n* store the md5sum of new packages at \"/\" or \"/flash\" for future checks on boot.\n\n## Notes on output files\n\n* `Base/_main.py`: the file is automatically called by the device before calling use space main.py.\n* `Custom/lib_a.py`: `lib_a` is a module that was part of the `directoriesKeptInFrozen`. This means that it will be globally available as a frozen module.\n* `Custom/_todefrost`: the folder contains 3 main file types\n  * `base64_\u003cid\u003e.py`: Each such file is a Python source file with two variables:\n    * `PATH`: the path where it needs to be extracted which is a concatenation of target's root folder from the configuration file (targetESP32, targetPycom) and the relative path of the file in the project.\n    * `DATA`: the contents of the file converted to Base64 and compressed with `zlib`.\n  * `package_md5sum.py`: an md5sum of the all the base64 Python files in `_todefrost`\n  * `microwave.py`: the script responsible of decompressing and converting the `DATA` of each base64 file and placing it to the destination folder defined by `PATH`\n\n# Method 2: Creating a simple update package with user code.\n\nApart from embedding a project into the firmware, an alternative way would be to pack all files that do not belong to `frozen` modules into one packet, send it to the device and unpack it.\n\n## prepare the configuration file\n\nThe configuration file is exactly the same as (Method 1). The only difference is that whatever files are found in the defined folder from `directoriesKeptInFrozen` are ignored.\n\n## run microfreezer\n\nReady to run microfreezer. The `config.json` needs to be present at the same path as microfreezer. If not, default values will be used as indicated above.\n\n```bash\n#python3 microfreezer.py (-v: verbose output) \u003cproject-folder-path\u003e \u003coutput-folder-path\u003e\npython3 microfreezer.py --ota-package ~/projects/my_new_project ~/projects/my_new_project_packed\n\n#or\n\npython3 microfreezer.py --ota-package -s ~/projects/my_new_project -d ~/projects/my_new_project_packed\n\n```\n\nThe output folder now contains 2 files:\n\n```\n|- _apply_package.py\n|- 1234567890abcdef1234567890abcdef.tar.gz\n```\n\nThe `tar.gz` can be send to the required devices and by importing the `_apply_package.py` at the same folder as the package, it...applies the package :P\n\n## Notes on output files\n\n* `\u003cmd5\u003e.tar.gz`: the zipped tar file that contains all required files and folders to be applied\n* `_apply_package.py`: searches for a `.tar` or `.tar.gz` file, decompresses it if needed, and untars the files using as base folder defined by the target in the configuration file (targetESP32, targetPycom).\n\n\n# Future work\n\n* auto-validation of package MD5 before or after decompression for package validity check\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsighio%2Fmicrofreezer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finsighio%2Fmicrofreezer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsighio%2Fmicrofreezer/lists"}