{"id":13746820,"url":"https://github.com/Blockstream/Jade","last_synced_at":"2025-05-09T07:32:45.753Z","repository":{"id":37936351,"uuid":"326499811","full_name":"Blockstream/Jade","owner":"Blockstream","description":"Jade hardware wallet","archived":false,"fork":false,"pushed_at":"2024-05-22T11:39:54.000Z","size":43983,"stargazers_count":278,"open_issues_count":37,"forks_count":38,"subscribers_count":26,"default_branch":"master","last_synced_at":"2024-05-22T17:26:43.376Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Blockstream.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"COPYING","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}},"created_at":"2021-01-03T21:00:44.000Z","updated_at":"2024-05-28T13:59:06.175Z","dependencies_parsed_at":"2023-02-13T00:00:33.395Z","dependency_job_id":"c6455d17-48ba-4df1-9539-e71c9eab05e3","html_url":"https://github.com/Blockstream/Jade","commit_stats":null,"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blockstream%2FJade","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blockstream%2FJade/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blockstream%2FJade/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Blockstream%2FJade/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Blockstream","download_url":"https://codeload.github.com/Blockstream/Jade/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224842481,"owners_count":17378982,"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":[],"created_at":"2024-08-03T06:01:02.280Z","updated_at":"2025-05-09T07:32:45.745Z","avatar_url":"https://github.com/Blockstream.png","language":"C","funding_links":[],"categories":["Uncategorized","C","Development Tools","Others"],"sub_categories":["Uncategorized"],"readme":"# Jade Firmware\n\nNOTE: the below instructions are for Jade developers with access to Jade development boards or for those wanting to build and flash their own esp32 consumer devices - eg. M5Stack or TTGO T-Display boards.\nThey are not for updating the firmware of an official Blockstream Jade hw unit - these can only be updated in-app, or using the 'update_jade_fw.py' script - see FWUPDATE.md\n\n* DO NOT ATTEMPT THE BELOW WITH BLOCKSTREAM OFFICIAL BLOCKSTREAM JADE HW UNITS\n\nTo build you can use the docker image (see Dockerfile) or install the esp-idf toolchain and repo following the commands in this readme.\n\n# DIY Hardware \u0026 Programming Notes\nFor information about suitable DIY hardware, as well as suggested configuration profiles and notes on secure boot.\n[DIY Guide](./diy/)\n\n# Use docker\n\nIf you are on MacOS, you are better off setting up the environment locally (see next step) than trying to get access to your device from the docker container. For more, see [this article](https://dev.to/rubberduck/using-usb-with-docker-for-mac-3fdd).\n\nNote the supplied docker-compose.yml assumes the Jade device is at /dev/ttyUSB0, but note that it may instead be /dev/ttyACM0 (or either with some other trailing number) or some other path as appropriate for the host operating system.\n\nNote the below instructions assume an original Jade v1.0 hardware with a true wheel.\nWhen using the later Jade v1.1 hw revision with a rocker/jog-wheel, use 'configs/sdkconfig_jade_v1_1.defaults' in place of 'configs/sdkconfig_jade.defaults'.\n```\n(local)$ docker-compose up -d\n(local)$ docker-compose exec dev bash\n(docker)$ cp configs/sdkconfig_jade.defaults sdkconfig.defaults\n(docker)$ idf.py flash\n```\n\nThe docker-compose.yml also mounts the local git repo so that it is the\norigin of the repo in the docker.\n\n# Set up the environment\n\nJade requires the esp-idf sdk.\n\nMore information is available in the [Espressif official guide](https://docs.espressif.com/projects/esp-idf/en/v5.4/esp32/get-started/index.html).\n\nGet the esp-idf sdk and required tools:\n\n```\nmkdir ~/esp\ncd ~/esp\ngit clone -b v5.4 --recursive https://github.com/espressif/esp-idf.git\ncd ~/esp/esp-idf \u0026\u0026 git checkout 67c1de1eebe095d554d281952fde63c16ee2dca0 \u0026\u0026 ./install.sh --enable-gdbgui esp32 esp32s3\npython ~/esp/esp-idf/tools/idf_tools.py install qemu-xtensa\n```\n\nSet up the environmental variables:\n\n```\n. $HOME/esp/esp-idf/export.sh\n```\n\nOn MacOS: You will need cmake and ninja on your system for this step (`brew install cmake ninja`).\n\nIf you encounter Python dependencies issue, make sure to use a recent Python version (e.g. Python 3.11) as the current system version which is used by the install script.\n\n# Build dependencies\n\nCmake and ninja are needed to build the firmware, you can install them on debian based distros with:\n\n``` \nsudo apt install cmake ninja-build\n```\n\n# Serial port\n\nIn order to have permissions using serial port to load firmware, your user should be in `dialout` group on debian \nbased distros, other distros can use a different group name, you can figure out by checking the group of the serial \nport 'file' using `ls -l` command:\n\n(serial port is usually `/dev/ttyACM0` or `/dev/ttyUSB0`)\n\n``` \n$ ls -l /dev/ttyACM0                                                                                                                     14:37:07\ncrw-rw----+ 1 root dialout 166, 0 Apr 15 14:37 /dev/ttyACM0\n```\n\nYou can check that `dialout` appear in your user groups by running:\n\n``` \n$ groups\ndocker libvirt dialout storage kvm wheel plugdev\n```\n\nif not present you should add your user to the group:\n\n``` \nsudo usermod -aG dialout $USER\n```\n\n(you should then login/logout or reboot)\n\n# Build the firmware\n\n```\ngit clone --recursive https://github.com/Blockstream/Jade.git $HOME/jade\ncd $HOME/jade\ngit submodule update --init --recursive\ncp configs/sdkconfig_jade.defaults sdkconfig.defaults\nidf.py flash monitor\n```\nUse a config file from the configs folder that is specific to your hardware (if available).\n\n_For example for the TTGO T-Display:_\n```\ncp configs/sdkconfig_display_ttgo_tdisplay.defaults sdkconfig.defaults\n```\n\nIf you flash multiple devices or make changes to the original config file that you used, make sure to delete the `sdkconfig` file that gets created from `sdkconfig.defaults`. Otherwise, your changes will not get picked up when building and re-flashing the firmware.\n\nSome hardware configurations (eg: M5StickC-Plus) may not support the default baud rate and won't be detected, so you can force a specific baud rate for flash/monitor by using the `-b` argument.\n\n_For example, the last line of the above code block would change be:_\n```\nidf.py -b 115200 flash monitor\n```\n\n# Build configurations\n\nThere are various build configurations used by the CI in the configs/ directory, which may be required for specific builds eg. without BLE radio, with the screen enabled (or disabled, as with the CI tests), or for specific hardware (eg. the m5-fire).\n\nThe menuconfig tool can also be used to adjust the build settings.\n\n```\nidf.py menuconfig\n```\nNote: for any but the simplest CI-like build with no GUI, no camera, no user-interaction etc. it is recommended that PSRAM is available and enabled.  ( Component Config -\u003e ESP-32 specific -\u003e Support external SPI connected RAM )\n\n# Run the tests\n\n```\ncd $HOME/jade\nvirtualenv -p python3 venv3\nsource venv3/bin/activate\npip install -r requirements.txt\n\npython test_jade.py\n\ndeactivate\n```\n\n# Emulator/Virtualizer (qemu in Docker)\n\nThe following will build a docker image running the headless ci-test (approves every request):\n```\ndocker build -t jade-qemu-ci -f Dockerfile.qemu .\ndocker run --rm -p 30121:30121 -it jade-qemu-ci\n```\nThe python 'jadepy' api can talk to it as if it were a serial interface, if given the device string 'tcp:localhost:30121'.\n```\npython -c \"from jadepy.jade import JadeAPI; jade = JadeAPI.create_serial(device='tcp:localhost:30121'); jade.connect(); print(jade.get_version_info()); jade.disconnect()\"\n```\n\nSimilarly, for a manually driven web-enabled 'virtual jade' (at 'http://localhost:30122/'):\n```\ndocker build -t jade-qemu-web -f Dockerfile.qemu --build-arg=\"SDK_CONFIG=configs/sdkconfig_qemu_psram_webdisplay.defaults\" .\ndocker run --rm -p 30121:30121 -p 30122:30122 -it jade-qemu-web\n```\n\nAlternatively, to run the qemu emulator with display and camera support is to run\n```\nmain/qemu/run_emulator.sh\n```\n\nThen you will be able to open the browser and point it to 'http://localhost:30122' to interface with the emulated Jade.\n\nNote that the ```run_emulator.sh``` command will launch a docker image so it will only work on Linux.\nYou can also optionally pass the flag ```--larger-display``` to run the emulator with a bigger display.\n\nOtherwise if you don't need the display or want to run with gdb, follow the below steps.\n\nRun these commands inside the jade source repo root directory, it will enter a docker container:\n\n```\nDOCKER_BUILDKIT=1 docker build . -t testjadeqemu\ndocker run -v ${PWD}:/jade -p 30121:30121 -it testjadeqemu bash\n```\n\nNote: You can skip the build step if you want by fetching the prebuilt image and running with\n\n```\ndocker pull blockstream/verde\ndocker run -v ${PWD}:/jade -p 30121:30121 -it blockstream/verde bash\n```\n\nNow inside the container\n\n```\n. /root/esp/esp-idf/export.sh\ncd /jade\nrm -fr sdkconfig\ncp configs/sdkconfig_qemu.defaults sdkconfig.defaults\nidf.py all\napt-get update -qq \u0026\u0026 apt-get install virtualenv -yqq\nvirtualenv -p python3 ./venv3\nsource ./venv3/bin/activate\npip install -r requirements.txt\n./tools/fwprep.py build/jade.bin build\n./main/qemu/make-flash-img.sh\n\n# To run the CI tests\n./main/qemu/qemu_ci_flash.sh\n\n# To reboot the qemu instance\n./main/qemu/qemu_reboot.sh\n\n# To reboot the qemu instance and attach gdb to the Jade fw\n./main/qemu/qemu_gdb.sh\n\n```\nAt this point the Jade fw running in the qemu emulator should be available on 'tcp:localhost:30121' from inside and outside the docker container.\n\n# Reproducible Build\n\nSee [REPRODUCIBLE.md](./REPRODUCIBLE.md) for instructions on locally reproducing the official Blockstream Jade firmware images (minus the Blockstream signature block).\n\n# DIY\n\nSeen working on M5 Stack gray/black/FIRE, M5 Stick Plus, Core 2, Core S3, LilyGO T-Display, T-DisplayS3, RPI Zero + display shield (via QEMU), Desktop via Qemu (browser for display/webcam)\n\n# Client\n\nA python client is available to communicate with genuine or diy Jade units:\n```\npip install jade-client\n```\nThis installs the `jadepy` directory from this repo.  See [jade-client-requirements.txt](./jade-client-requirements.txt) and [jade-client-requirements.txt.asc](./jade-client-requirements.txt.asc)\n\n# License\n\nThe collection is subject to gpl3 but individual source components can be used under their specific licenses.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBlockstream%2FJade","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBlockstream%2FJade","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBlockstream%2FJade/lists"}