Build Instructions

Collapse

• 1

  How to use ZeroKeyUSB

  Screen-by-screen walkthrough of the wizard that appears the first time you plug your ZeroKeyUSB in. Orientation, keyboard layout and master PIN.

  The first time you plug your ZeroKeyUSB into a USB-C port, a 9-page setup wizard starts automatically (in Spanish by default — the localized strings appear below). This guide walks you from the welcome screen to a device ready to store credentials.
  

  Step 1 — Welcome splash

  When you plug the cable in, the OLED lights up showing the bootloader logo for a couple of seconds. This confirms that the firmware booted correctly and the ECDSA signature of the binary has been validated by the ATECC608A secure element.
  

  Wait about 2 seconds. The wizard appears automatically — you don’t have to press anything.

  Step 2 — Page 1: Welcome

  First page of the wizard. The inverted top bar shows the title and a page indicator <1/9>. The body briefly describes what the device is and what to do.
  

  Press Right to advance. If the body has more text than fits on screen, use Up/Down to scroll before continuing.

  Step 3 — Page 2: Navigation

  Explains what each of the 5 pads does. This is the only page that describes the controls explicitly.
  

  Read the page and press Right to move to the next one.

  Step 4 — Page 3: Rotate screen

  If the golden dots end up on your left instead of on the right, flip the device physically — or rotate the screen in software with Center. The orientation is saved in EEPROM and persists across power cycles.
  

  Press Center to toggle the orientation (you will see NORMAL ↔ ROTADA on screen). When the controls feel right, press Right to continue.

  Step 5 — Page 4: Keyboard layout

  ZeroKeyUSB emulates a USB keyboard. So that passwords with special characters (@, !, #, etc.) type correctly on your computer, the device needs to know your keyboard layout.
  

  Press Center to cycle through EN-US, ES-ES, FR-FR, DE-DE, IT-IT, PT-PT, DA-DK, SV-SE, HU-HU. When yours appears, press Right.

  You can change this later from Menu → Settings → Keyboard.

  Step 6 — Page 5: Master PIN (introduction)

  This page explains the PIN rules before asking for one. Pick between 4 and 16 digits (0–9). It is the only thing standing between an attacker and your credentials.
  

  Press Center to move on to the PIN entry screen.

  There is no PIN recovery. If you forget it, the only option is a factory reset that wipes all your credentials. Memorize the PIN — or write it down somewhere physically safe.

  Step 7 — Enter the PIN

  The numpad screen. Each digit is entered with Up/Down (to choose 0–9) and Right (to confirm and advance to the next digit). The small arrows on the sides of the active digit remind you of the available moves.
  

  For each digit of your PIN: Up/Down to the correct number, then Right to confirm it. When you finish the last digit, the cursor jumps to the tick (✓) symbol. Press Center on the tick to save the PIN.

  To erase the last digit if you make a mistake, press Left.

  Step 8 — Page 6: PIN saved

  After entering the PIN, the wizard shows it back to you once so you can memorize it. This is your last chance to see it in cleartext.
  

  Write the PIN down or memorize it. When you have it, press Right.

  Step 9 — Page 7: Unlocking

  Explains that from now on, every time you plug the USB in, you will have to enter the PIN. And that repeated failures trigger an exponential wait.
  

  Read the page and press Right to continue.

  Exponential backoff: first failure = 5 s wait, second = 10 s, third = 20 s… up to ~43 min max. The counter resets when you enter the correct PIN. Nothing is wiped automatically.

  Step 10 — Page 8: Accounts

  A preview of the main screen — how credentials are navigated once you are unlocked.
  

  Press Right.

  Step 11 — Page 9: All set

  Last page. Reminds you that you can reach the main menu by pressing Left on the first credential (or Right on the last, going through “Add New” first).
  

  Press Center to exit the wizard and reach the PIN screen. That’s it — the device is set up.

  Step 12 — Ready to use

  After pressing Center, the device takes you to the PIN numpad to enter the PIN you just created (the same one you will see every time you plug the device in from now on). When you enter the PIN correctly, you will reach the main screen — but since there are no credentials yet, the Add New screen appears directly.
  

  Press Center to create your first credential — or follow the dedicated guide at Create your first credential.

• 2

  Managing credentials with the WebTool

  Restore from a backup or migrate from another password manager. Screen by screen, from the menu to imported data.

  Import loads credentials (site, username, password and optionally a TOTP secret) from a CSV file over USB serial. It happens after unlocking the device and requires physical authorization via the Center button.
  

  Import overwrites the destination slots without asking. If you already have credentials, create a backup (guide) before continuing.

  Before you start

  You need	How to get it
  >td >Plug it in and enter your PIN
  A CSV file with your credentials	A previous export, or an export from 1Password / Bitwarden / Keepass adapted to the format (see below)
  A serial tool	Web manager (recommended), screen, minicom, PuTTY at 115200 bps

  Step 1 — Open the menu

  While on the first credential, press Left.
  

  Press Left while on credential 1.

  Step 2 — Enter the Backup submenu

  In the root menu, Backup is selected by default. Press Center.
  

  Press Center.

  Step 3 — Select “Import”

  Inside Backup, Import is at the top. If it’s not highlighted, press Up to reach it. Then Center.
  

  With Import highlighted, press Center.

  Step 4 — Physical authorization

  Just like in export, an authorization screen asks for a long Center press before enabling the import channel.
  

  Before continuing, prepare your CSV file on the host. When ready, hold Center for ~1 second. The device sends REQUEST_SAVE over USB serial waiting for the data.

  Don’t press Center short by mistake — a short press won’t authorize anything (it just moves to the next menu screen if there is one).

  Step 5 — Send the CSV from the host

  With the device in “waiting for data” mode, send over USB serial:
  

  1. A line with the total number of records to import (example: 5).
  2. One CSV line per credential in this format:

     slotIndex,site,username,password[,totpSecret]
     

  Full example:

  5
  0,github.com,alice,MyP@ss123,JBSWY3DPEHPK3PXP
  1,gmail.com,bob@gmail.com,correct horse battery staple
  2,bank.com,12345678X,s3cur3P@ss,JBSWY3DPEHPK3PXP;algo=SHA256
  3,aws-prod,admin,A!7zQ#mYpL2v
  4,banca,12345678X,Pin-only2FA
  

  Each line is processed like this:

  Host → device:   "0,github.com,alice,MyP@ss123,JBSWY3DPEHPK3PXP"
  Device:          AES-128 CBC encrypt → write to EEPROM slot 0
  Device → host:   "Record 1 stored correctly."
  

  The web manager has a file picker that sends the lines in the right order and shows progress. If you don’t want to fight with the terminal, use it.

  Step 6 — Progress

  During import you’ll see the slot being written and overall progress on screen.
  

  When done, the device shows “Import complete” for 1 second and returns to the menu. Press Left to exit to the credential list and verify they’ve been added.

  Step 7 — Verify

  Press Left repeatedly to exit the menu to the credential list. Navigate with Left/Right and check that the imported data appears.
  

  Use Right to walk through the newly imported credentials. If everything looks good, consider making a new backup now.

  CSV format

  Field	Description	Limit
  slotIndex	Target slot	0–61
  site	Site or service	16 characters
  username	Username	16 characters
  password	Password	Any printable ASCII
  totpSecret	(optional) TOTP secret	See below

  Accepted TOTP secret formats

  Format	Example
  Bare Base32	JBSWY3DPEHPK3PXP
  Base32 + algorithm	JBSWY3DPEHPK3PXP;algo=SHA256
  Full otpauth:// URI	otpauth://totp/GitHub:alice?secret=JBSWY3DPEHPK3PXP&algorithm=SHA256

  Default algorithm if not specified: SHA-1.
  

  Validation and errors

  Case	Behaviour
  slotIndex outside 0–61	Reject the line: "Index out of range"
  Invalid Base32	Reject the TOTP secret: "TOTP invalid"
  Line with fewer than 3 fields	Skipped with an error log
  Empty line	Terminates the import early

  Migrating from other managers

  To migrate from 1Password, Bitwarden, Keepass and others:
  

  1. Export to CSV in the source manager.
  2. Adapt the CSV to the ZeroKeyUSB format (a simple Python script — trim each field to 16 chars and reorder columns).
  3. Import following this guide.

• 3

  Editing credentials directly on ZeroKeyUSB

  How to open the editor, move the cursor, use the three keyboard pages, generate random passwords and save.

  This guide details every operation in the on-device editor. If you just want to create your first credential, start with the Create your first credential guide.
  

  Step 1 — Select the credential

  From the main screen, navigate to the credential you want to edit using Left/Right. If you have many, hold Left/Right to jump 10 slots at a time.
  

  When the right credential is on screen (you’ll see its number at the top left — here 4), move on to the next step.

  Step 2 — Select the field and open the editor

  The active field shows as an inverted white block on the left (globe = site, silhouette = user, padlock = password, key = 2FA). Switch between fields with Down/Up:
  

  • Site ↓ User ↓ Pass ↓ 2FA (if the credential has TOTP)

  When you’re on the right field, hold Center for ~1 second to enter the editor.
  

  A short Center press types the field to the host (not what you want). A long press (~800 ms, until you see the large halo) opens the editor.

  Step 3 — Editor anatomy

  The editor looks like this:
  

  Element	Function
  Row 1	Shows the current field content (max 16 chars) with an inverted cursor at the insertion point
  Row 2 — < >	Move the field cursor (insertion position)
  Row 2 — KB1	Uppercase keyboard: A B C D E F G H I J K L M N O P
  Row 3 — Rand	Fills the entire field with 12 strong random characters
  Row 3 — KB2	Lowercase keyboard: a b c d e f g h i j k l m n o p
  Row 4 — Save	Saves changes and returns to the main view
  Row 4 — KB3	Numbers/symbols: 0 1 2 3 4 5 6 7 8 9 - + ! @ #

  Step 4 — Move the cursor across the keyboard

  When you enter the editor, focus starts on KB1 (row 2). Left/Right move the keyboard cursor within the current row.
  

  Press Right to advance the keyboard cursor, Left to go back. At the end/start, the cursor jumps to the control in the adjacent row (Rand, Save, <, >).

  Step 5 — Insert a character

  With the desired character under the keyboard cursor, press Center. It gets inserted at the field cursor’s current position, which then advances automatically.
  

  The L is inserted at position 5 of the field and the field cursor advances to position 6. If you wanted to replace instead of insert, read the next step.

  Step 6 — Move the field cursor (not the keyboard)

  Sometimes you want to edit characters in the middle of the field, not just append to the end. For that, use the < and > symbols on row 2.
  

  Reach the < or > symbol with Left (from KB1) and press Center. The field cursor moves one position left or right. When it’s on the position you want to edit, go back to KB1/KB2/KB3 and press Center on the new letter — it overwrites the existing one.

  Keyboard insertions overwrite the character at the current position, they don’t push existing content. So “deleting” a character is simply moving onto it and entering a space (KB3, first character).

  Step 7 — Generate a random password

  For password fields, instead of typing letter by letter, use Rand: 12 alphanumeric + symbol characters from the ATECC608A’s hardware TRNG.
  

  Navigate to Rand with Down from row 2. Press Center: the field fills up. If you don’t like it, press Center again to regenerate.

  Step 8 — Save

  When you’re done, navigate to Save (bottom-left corner) and press Center. The changes are encrypted with AES-128 CBC and written to EEPROM.
  

  The editor closes and you return to the main view. The credential now has the changes.

  Leaving the editor without pressing Save discards the changes. There is no confirmation: the moment you change screen via any path other than Save, what you typed is lost.

  Shortcut table

  Action	How
  Enter the editor	Long-press Center on a field
  Move keyboard cursor	Left/Right
  Change row/keyboard	Up/Down
  Insert character	Center on the letter
  Move field cursor	Center on < or > (row 2)
  “Delete” a character	Move the cursor there and insert space (KB3 first character)
  Generate random password	Center on Rand
  Save and exit	Center on Save
  Discard changes	Unplug USB before pressing Save

  
  

View all 3 instructions