{"id":14980036,"url":"https://github.com/coldcard/firmware","last_synced_at":"2025-05-15T03:06:07.884Z","repository":{"id":34508274,"uuid":"142194760","full_name":"Coldcard/firmware","owner":"Coldcard","description":"❄️ Firmware and simulator for Coldcard Hardware Wallet","archived":false,"fork":false,"pushed_at":"2025-05-09T14:13:52.000Z","size":30484,"stargazers_count":637,"open_issues_count":4,"forks_count":159,"subscribers_count":37,"default_branch":"master","last_synced_at":"2025-05-09T15:30:21.378Z","etag":null,"topics":["bitcoin","bitcoin-wallet","cryptocurrency","cryptography","security"],"latest_commit_sha":null,"homepage":"http://coldcard.com","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Coldcard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING-CC","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security-model.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-07-24T17:59:44.000Z","updated_at":"2025-05-09T14:13:56.000Z","dependencies_parsed_at":"2023-10-16T10:59:05.854Z","dependency_job_id":"bc03f438-36a2-490f-ae69-e1b49e142bdc","html_url":"https://github.com/Coldcard/firmware","commit_stats":{"total_commits":3065,"total_committers":47,"mean_commits":65.2127659574468,"dds":"0.17553017944535076","last_synced_commit":"114d1dd675e6ac22147568c621d46d71678462e1"},"previous_names":[],"tags_count":159,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Coldcard%2Ffirmware","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Coldcard%2Ffirmware/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Coldcard%2Ffirmware/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Coldcard%2Ffirmware/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Coldcard","download_url":"https://codeload.github.com/Coldcard/firmware/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254264765,"owners_count":22041793,"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","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":["bitcoin","bitcoin-wallet","cryptocurrency","cryptography","security"],"created_at":"2024-09-24T14:01:11.924Z","updated_at":"2025-05-15T03:06:07.400Z","avatar_url":"https://github.com/Coldcard.png","language":"Python","readme":"# COLDCARD Hardware Wallet\n\nColdcard is an Affordable, Ultra-secure \u0026 Verifiable Hardware Wallet for Bitcoin.\nGet yours at [Coldcard.com](http://coldcard.com)\n\n[Follow @COLDCARDwallet on Twitter](https://twitter.com/coldcardwallet) to keep up\nwith the latest updates and security alerts.\n\n![coldcard logo](https://coldcard.com/static/images/coldcard-logo-nav.png)\n\n![Mk4 coldcard picture front](https://coldcard.com/static/images/mk4.png)\n\n## Quick Links\n\n- [Latest firmware changes and updates](releases/ChangeLog.md)\n- [PGP signature file](releases/signatures.txt)\n- [Firmware binaries](https://coldcard.com/downloads)\n\n## Reproducible Builds\n\nTo have confidence this source code tree is the same as the binary on your device,\nyou can rebuild it from source and get **exactly the same bytes**. This process\nhas been automated using Docker. Steps are as follows:\n\n1. Install [Docker](https://www.docker.com) and start it.\n2. Install [make (GNUMake)](https://www.gnu.org/software/make/) if you don't already have it.\n3. Checkout a specific version of the code, and start the process.\n\n    ```shell\n    git clone https://github.com/Coldcard/firmware.git\n    git checkout 2023-12-21T1526-v5.2.2\n    # get a copy of that binary into ./releases/2023-12-21T1526-v5.2.2-mk4-coldcard.dfu\n    cd firmware/stm32\n    make -f MK4-Makefile repro\n    ```\n\n4. At the end of the process a clear confirmation message is shown, or the differences.\n5. Build products can be found `firmware/stm32/built`.\n6. If you do not trust the results of `make repro` refer to `docs/notes-on-repro.md`\n   which breaks down the process.\n7. Process for Q firmware is the same, but change `MK4-Makefile` in last step to `Q1-Makefile`\n\n## Long-Lived Branches\n\nWe are now maintaining two branches: `master` and `edge`.\n\n\"Edge\" will contain features that may not be ready for prime time,\nsuch as Taproot or Miniscript. Our standards for releasing new Edge\nversions are lower, so we can iterate faster and get these advancements\nout to other developers.\n\nQ and Mk4 share the same code base. Individual files that are added,\nor removed, can be see in differences between `shared/manifest_mk4.py`\nand `shared/manifest_q1.py`. Common files are in `shared/manifest.py`.\n\n\n## Check-out and Setup\n\n**NOTE** This is the `master` branch and covers the latest hardware (Mk4 and Q).\nSee branch `v4-legacy` for firmware which supports only Mk3/Mk2 and earlier.\n\nDo a checkout, recursively, to get all the submodules:\n\n```shell\ngit clone --recursive https://github.com/Coldcard/firmware.git\n```\n\nAlready checked-out and getting git errors? Do this:\n\n```shell\ngit fetch\ngit reset --hard origin/master\n```\n\nAlternatively, to get the latest release, you checkout a tagged branch:\n\n```shell\ngit clone https://github.com/Coldcard/firmware.git\ncd firmware\ngit checkout $(git describe --match \"20*\" --abbrev=0)\ngit submodule update --init --recursive\n```\n\nDo not use a path with any spaces in it. The Makefiles do not handle\nthat well and we're not planning to fix it.\n\nKeep in mind that python requirements may change between versions,\nso at the top level, do this command:\n\n```shell\npip install -r requirements.txt\n```\n\n### macOS\n\n[Python 3.5 or higher](https://www.python.org) and [Homebrew](https://brew.sh) is required.\n\nIf working on an ARM-based MacOS system, you may want to create a\nnew shell with `arch -x86_64 bash` before starting, or continuing\nto work on this source tree.\n\n#### Setup and run the desktop simulator\n\nYou'll probably need to install at least these packages:\n\n```shell\nbrew install sdl2 xterm swig\nbrew install --cask xquartz gcc-arm-embedded\n```\n\nUsed to be these were needed as well:\n\n```shell\nbrew tap PX4/px4\nbrew search px4/px4/gcc-arm-none-eabi\n```\n\nThen install the newest version, currently 83:\n\n```shell\nbrew install px4/px4/gcc-arm-none-eabi-83\n```\n\nYou may need to `brew upgrade gcc-arm-embedded` because we need 10.2 or higher.\n\nThen:\n\n```shell\nbrew install automake autogen virtualenv\nvirtualenv -p python3 ENV\nsource ENV/bin/activate (or source ENV/bin/activate.csh based on shell preference)\npip install -U pip\npip install -r requirements.txt\n# apply micropython patch\npushd external/micropython\ngit apply ../../macos-mpy.patch\npopd\nmake -C external/micropython/mpy-cross\ncd unix; make setup \u0026\u0026 make ngu-setup \u0026\u0026 make \u0026\u0026 ./simulator.py\n```\n\nYou may need to reboot to avoid a `DISPLAY is not set` error.\n\nThe next time you want to run the simulator, you can simply do\n\n```shell\nsource ENV/bin/activate \u0026\u0026 cd unix \u0026\u0026 ./simulator.py\n```\n\n#### Building the firmware\n\n- `cd ../cli; pip install --editable .`\n- `cd ../stm32; make setup \u0026\u0026 make; make firmware-signed.dfu`\n- The resulting file, `firmware-signed.dfu` can be loaded directly onto a Coldcard, using this\n  command (already installed based on above)\n- `ckcc upgrade firmware-signed.dfu`\n\nWhich looks like this:\n\n```shell\n[ENV] [firmware/stm32 42] ckcc upgrade firmware-signed.dfu  \n675328 bytes (start @ 293) to send from 'firmware-signed.dfu'\nUploading  [##########--------------------------]   29%  0d 00:01:04\n```\n\n#### Big Sur Issues\n\n`defaults write org.python.python ApplePersistenceIgnoreState NO` will suppress a warning about `Python[22580:10101559] ApplePersistenceIgnoreState: Existing state will not be touched. New state will be written to...`\n\nSee \u003chttps://bugs.python.org/issue32909\u003e\n\n### Linux\n\nAll steps you need to install and run the Coldcard simulator on Ubuntu 20.04:\n\n\n```shell\n# Install (system) requirements, tools and libraries\napt install build-essential git python3 python3-pip libudev-dev gcc-arm-none-eabi libffi-dev xterm swig libpcsclite-dev python-is-python3 autoconf libtool python3-venv\n\n# Get sources, this takes a long time (because of external libraries), then open\ngit clone --recursive https://github.com/Coldcard/firmware.git\ncd firmware\n\n# Apply address patch\ngit apply unix/linux_addr.patch\n\n#  * below is needed for ubuntu 24.04\npushd external/micropython\ngit apply ../../ubuntu24_mpy.patch\npopd\n#  * \n\n\n# Create Python virtual environment and activate it\npython3 -m venv ENV  # or virtualenv -p python3 ENV\nsource ENV/bin/activate\n\n# Install dependencies\npip install -U pip setuptools\npip install -r requirements.txt #general requirements\npip install pysdl2-dll # Ubuntu needs this dependency\n\n# Build the Coldcard simulator\ncd unix\npushd ../external/micropython/mpy-cross/\nmake  # mpy-cross\npopd\nmake setup\nmake ngu-setup\nmake\n\n# Run the simulator in the active virtualenv\n./simulator.py\n\n# Later, if you want to run it (after a reboot). This assumes you extracted the git repo in ~ (home)\ncd ~/firmware\nsource ENV/bin/activate\ncd unix\n./simulator.py\n```\n\nAlso make sure that you have your python3 symlinked to python.\n\n## Code Organization\n\nTop-level dirs:\n\n`shared`\n\n- shared code between desktop test version and real-deal\n- expected to be largely in python, and higher-level\n- new code found only on the Mk4 will be listed in `manifest_mk4.py` code exclusive\n  to earlier hardware is in `manifest_mk3.py`\n\n`unix`\n\n- unix (macOS) version for testing/rapid dev\n- this is a simulator for the product\n\n`testing`\n\n- test cases and associated data\n\n`stm32`\n\n- embedded binaries (and building), for actual product hardware\n- final target is a binary file for loading onto hardware\n\n`external`\n\n- code from other projects, ie. the dreaded submodules\n\n`graphics`\n\n- images which ship as part of the final product (icons)\n\n`stm32/bootloader`\n\n- 32k of factory-set code that you cannot change (Mk3)\n- however, you can inspect what code is on your coldcard and compare to this.\n\n`stm32/mk4-bootloader`\n`stm32/q1-bootloader`\n\n- 128k of factory-set code that you cannot change for Mk4 or Q\n- however, you can inspect what code is on your coldcard and compare to this.\n\n`hardware`\n\n- schematic and bill of materials for the Coldcard, all versions.\n\n`unix/work/...`\n\n- `/MicroSD/*` files on \"simulated\" microSD card\n\n- `/VirtDisk/*` simulated emulated virtual Disk files.\n\n- `/settings/*.aes` persistent settings for Simulator\n\n## Support\n\nFound a bug? Email: support@coinkite.com\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoldcard%2Ffirmware","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoldcard%2Ffirmware","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoldcard%2Ffirmware/lists"}