{"id":22253633,"url":"https://github.com/nitrokey/nitrokey-storage-firmware","last_synced_at":"2025-07-28T05:32:43.031Z","repository":{"id":23410560,"uuid":"26772940","full_name":"Nitrokey/nitrokey-storage-firmware","owner":"Nitrokey","description":"Firmware for the Nitrokey Storage device","archived":false,"fork":false,"pushed_at":"2023-08-09T13:37:53.000Z","size":267205,"stargazers_count":54,"open_issues_count":51,"forks_count":19,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-07-18T07:42:23.887Z","etag":null,"topics":["c","device","firmware","gplv3","mass-storage-device","nitrokey-stick-devices","nitrokey-storage","otp","security","smartcard-reader"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Nitrokey.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}},"created_at":"2014-11-17T19:20:22.000Z","updated_at":"2023-08-12T00:24:37.000Z","dependencies_parsed_at":"2022-08-07T11:00:29.991Z","dependency_job_id":null,"html_url":"https://github.com/Nitrokey/nitrokey-storage-firmware","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/Nitrokey/nitrokey-storage-firmware","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nitrokey%2Fnitrokey-storage-firmware","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nitrokey%2Fnitrokey-storage-firmware/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nitrokey%2Fnitrokey-storage-firmware/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nitrokey%2Fnitrokey-storage-firmware/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Nitrokey","download_url":"https://codeload.github.com/Nitrokey/nitrokey-storage-firmware/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nitrokey%2Fnitrokey-storage-firmware/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267468347,"owners_count":24092329,"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-07-28T02:00:09.689Z","response_time":68,"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":["c","device","firmware","gplv3","mass-storage-device","nitrokey-stick-devices","nitrokey-storage","otp","security","smartcard-reader"],"created_at":"2024-12-03T07:19:14.637Z","updated_at":"2025-07-28T05:32:42.464Z","avatar_url":"https://github.com/Nitrokey.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nitrokey Storage Firmware\n\n## Firmware verification\nTo verify firmware flashed on device, please use the Nitrokey Storage Firmware Checksum Tool from the [tools] directory.\n\n[tools]: https://github.com/Nitrokey/nitrokey-storage-firmware/tree/master/tools\n\n## Building\n\n### Windows\nNote: Tested with Windows 7\n\nInstall the following tools in this order:\n\n1. [avr32-gnu-toolchain-2.4.2-setup.exe](http://www.atmel.com/System/BaseForm.aspx?target=tcm:26-17439)\n2. [avr32studio-ide-installer-2.5.0.35-win32.win32.x86.exe](http://www.atmel.com/tools/studioarchive.aspx)\n3. [AvrStudio4Setup.exe](http://www.atmel.com/tools/studioarchive.aspx)\n4. [AVRStudio4.18SP2.exe](http://www.atmel.com/System/BaseForm.aspx?target=tcm:26-41051)\n\n### Linux\n\n#### GUI\nThe compile procedure is as follows (tested on ArchLinux but should work on any\nother GNU/Linux OS):\n1. Clone this git project (`git clone https://github.com/Nitrokey/nitrokey-storage-firmware.git`)\n2. Download and extract [AVR32 Studio](https://www.microchip.com/mplab/avr-support/avr-and-sam-downloads-archive). Example archive filename: `avr32studio-ide-2.6.0.753-linux.gtk.x86_64.zip`. At the moment no newer version seems to be available for Linux.\n3. Start AVR32 Studio by executing `avr32studio` in the extracted folder.\n4. Import project into AVR32 Studio: File | Import... | General | Existing Projects into Workspace | Choose the folder of downloaded git project.\n5. Rename `pm_240.h` in the git project folder to `pm_231.h`. Make a backup of `as4e-ide/plugins/com.atmel.avr.toolchains.linux.x86_64_3.0.0.201009140852/os/linux/x86_64/avr32/include/avr32/pm_231.h`. Replace that `pm_231.h` with the renamed `pm_240.h`.\n6. In AVR32 Studio select Project | Build All.\n7. The builded file is now in the folder `Debug` of the git project folder.\n\n#### Command Line\n\n```\n# setup\nTOOLCHAIN_PATH=as4e-ide\nT_SUBPATH=plugins/com.atmel.avr.toolchains.linux.x86_64_3.0.0.201009140852/os/linux/x86_64/avr32/include/avr32\nmv $(TOOLCHAIN_PATH)/$(T_SUBPATH)/pm_231.h{,~} -v\ncp pm_240.h $(TOOLCHAIN_PATH)/$(T_SUBPATH)/pm_231.h\n# firmware build\ncd src \u0026\u0026 make CC=path/to/avr32-gcc\n```\n\n\n#### Converting to .HEX file\nBefore flashing there may be a need to convert binary file to .hex. If it was not done automatically execute the following in Debug or Release directory:\n```\navr-objcopy -R .eeprom -O ihex USB_MASS.elf firmware.hex\n```\nor, while in `./Debug` directory:\n```\nmake firmware.hex\n```\n\n## Flashing the Firmware to Device\n\n- [Latest firmware releases](https://github.com/Nitrokey/nitrokey-storage-firmware/releases/latest)\n- [General documentation](https://docs.nitrokey.com/storage/)\n- Firmware upgrade instructions:\n    - [Windows](https://docs.nitrokey.com/storage/windows/firmware-update.html)\n    - [macOS](https://docs.nitrokey.com/storage/mac/firmware-update.html)\n    - [Linux](https://docs.nitrokey.com/storage/linux/firmware-update.html)\n    - [(previous documentation)](https://www.nitrokey.com/documentation/firmware-update-storage)\n\n## Debugging\n**Note: To connect an external debugger as described here, you will need a development version of the Nitrokey Storage that makes the JTAG pins available (pictured below). This version is currently not for sale.**\nThe PCB layout for the developer version can be found in the [Nitrokey Storage Hardware](https://github.com/Nitrokey/nitrokey-storage-hardware) repository, inside the dev folders.\n\n![NK Storage Development Version](/img/nkstorage_jtag.jpg \"Nitrokey Storage Development Version\")\n\n### Compatible Debuggers\nThis has been tested with the [AVR JTAGICE XPII](https://www.waveshare.com/product/mcu-tools/avr/programmers-debuggers/usb-avr-jtagice-xpii.htm), however the more recent [Atmel ICE](http://www.microchip.com/DevelopmentTools/ProductDetails.aspx?PartNO=atatmel-ice) and any other AVR UC3 compatible debugger should work as well.\n\n### Prepare connections\nThe JTAG connections on the PCB have a pitch of 1.27mm. To ease connecting and disconnecting, it is easiest to solder a pin header to the PCB and use a pin socket to quickly attach the device to the debugger. It is recommended to use the following parts for that (however any connector with a 1.27mm pitch will work):\n\n| Part                                  | Digikey Part Number       |\n|---                                    |---                        |\n| 7-pin THT Pin header, 1.27mm Pitch    |  S9014E-07-ND             |\n| 7-pin THT Pin header, 2.54mm Pitch    |  S1012EC-07-ND            |\n| 7-pin Socket, 1.27mm Pitch            |  S9008E-07-ND             |\n| 1.27mm Ribbon Cable, ca. 15cm         |                           |\n| Heatshrink                            |                           |\n\n- Solder the 1.27mm Pin header to the board\n- Solder the 1.27mm socket and 2.54mm header to the cable and isolate individual contacts with heatshrink\n\n### Connect Debugger interface to the Nitrokey\n\nUse jumper wires to connect the cable from the Nitrokey to the Debugger interface connector as pictured below:\n\n![NK Storage Debugger Connection](/img/debugger_connection.png)\n\n| Nitrokey Side                         | AVR JTAG Connector Side   |\n|---                                    |---                        |\n| RST                                   | nSRST                     |\n| TCK                                   | TCK                       |\n| TDI                                   | TDI                       |\n| TDO                                   | TDO                       |\n| TMS                                   | TMS                       |\n| GND                                   | GND                       |\n| VDD                                   | VTref                     |\n\nThe device still needs to be powered via USB during debugging.\nFor an initial function test, you can issue the following commands from the AVR32Studio home directory:\n\n```\ncd /plugins/com.atmel.avr.utilities.linux.x86_64_3.0.0.201009140848/os/linux/x86_64/bin\n./avr32program --part UC3A3256S cpuinfo\n```\nif the device is connected correctly, this should yield an output similar to this:\n```\nConnected to JTAGICE mkII version 6.6, 6.6 at USB.\n\nDevice information:\nDevice Name                                   UC3A3256S \nDevice Revision                               H\nJTAG ID                                       0x7202003f\nSRAM size                                     128 kB\nFlash size                                    256 kB\n```\n\n### Using the debugger in AVR32Studio\n\nTo enable the debugger, follow these steps inside the IDE:\n- Enable the \"AVR Targets\" dialog under `Window -\u003e Show View -\u003e AVR Targets`\n- Right click inside the \"AVR Targets\" window and select `Scan Targets`. Your debugger should now be shown as a target.\n- Right click on the debugger entry and select `Properties`\n- Select the \"Details\" tab. Under \"Device\", select `AVR UC3A Series -\u003e AT32UC3A3256S`\n\nThe debugger should now be available. Configure the debugging environment by following these steps:\n- Open `Run -\u003e Debug Configurations`\n- If there is no entry under `AVR Application`, create one by double clicking on it. Otherwise select the existing entry.\n- Under \"File\", select `Debug/USB_MASS.elf`\n- Under \"Target\" select `JTAGICE mkII` (or your correspondig JTAG debugger)\n- Under \"Erase Options\" select `Erase sectors`\n- Under \"Run Options\" select `Reset MCU`\n- Apply Settings and close the dialog window\n\nCongratulations, your IDE should now be ready for debugging. Set breakpoints as needed and start a JTAG debugging session by pressing F11.\n\n### Defaulting to USB DFU\nIf you accidentally erased the DFU bootloader from the chip or run into any trouble, the stick can always be reprogrammed like this:\n- In the \"AVR Targets\" dialog, right click on your JTAG debugger and select `Program Bootloader`\n- Leave all the entries in their default state and reprogram the bootloader by clicking `Finish`\n\nThe device will now start in DFU mode and can be programmed as described above in the Firmware Upgrade Instructions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnitrokey%2Fnitrokey-storage-firmware","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnitrokey%2Fnitrokey-storage-firmware","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnitrokey%2Fnitrokey-storage-firmware/lists"}