mirror of
https://github.com/trezor/trezor-firmware.git
synced 2024-12-16 19:38:09 +00:00
233 lines
6.3 KiB
Markdown
233 lines
6.3 KiB
Markdown
|
# Production Test Firmware
|
||
|
This document outlines the protocol used during production for testing and the initial provisioning of Trezor devices.
|
||
|
|
||
|
## Commands and Responses
|
||
|
In the production environment, the test equipment sends single-line text commands.
|
||
|
These commands start with the command name and can optionally be followed by parameters separated by spaces.
|
||
|
|
||
|
Command Format:
|
||
|
|
||
|
`COMMAND [INARG1 [INARG2 [INARG3 ...]]]`
|
||
|
|
||
|
Example:
|
||
|
```
|
||
|
CPUID READ
|
||
|
```
|
||
|
|
||
|
The Trezor device responds with single-line text responses that start with either `OK` or `ERROR`, followed by output values separated by spaces.
|
||
|
If the device receives an unrecognized command, it responds with the text `UNKNOWN`.
|
||
|
|
||
|
Device responds with single line text response starting with words `OK` or `ERROR` optionally followed by output values delimited by spaces.
|
||
|
In case of unrecognized command, device responds with text `UNKNOWN`.
|
||
|
|
||
|
Response Format:
|
||
|
|
||
|
`OK [OUTARG1 [OUTARG2 [OUTARG3 ...]]]`
|
||
|
|
||
|
Example:
|
||
|
```
|
||
|
OK 2F0079001951354861125762
|
||
|
```
|
||
|
|
||
|
## List of commands
|
||
|
|
||
|
### PING
|
||
|
The `PING` command serves as a no-operation request, and the device responds with `OK` to acknowledge receipt.
|
||
|
|
||
|
Example:
|
||
|
```
|
||
|
PING
|
||
|
OK
|
||
|
```
|
||
|
|
||
|
### CPUID READ
|
||
|
The `CPUID READ` command reads a 96-bit long unique ID stored in the device's CPU.
|
||
|
The command always returns `OK` followed by a 24-digit hexadecimal value representing the unique ID.
|
||
|
|
||
|
Example:
|
||
|
```
|
||
|
CPUID READ
|
||
|
OK 2F0079001951354861125762
|
||
|
```
|
||
|
|
||
|
### BORDER
|
||
|
The `BORDER` command draws a single white border around the screen on a black background. This command has no input parameters and always returns `OK`.
|
||
|
|
||
|
Example:
|
||
|
```
|
||
|
BORDER
|
||
|
OK
|
||
|
```
|
||
|
|
||
|
### DISP
|
||
|
The `DISP` command draws vertical color bars on the screen based on a list of specified colors provided as a parameter.
|
||
|
Each character in the parameter represents one vertical bar and its color (R - red, B - blue, W - white, any other character - black).
|
||
|
The number of characters corresponds to the number of bars.
|
||
|
|
||
|
Note: On monochromatic displays R, G, B characters are interpreted as the white color.
|
||
|
|
||
|
Example (to draw 6 vertical bars - red, black, green, black, blue and black):
|
||
|
```
|
||
|
DISP RxGxB
|
||
|
```
|
||
|
|
||
|
### BUTTON
|
||
|
The `BUTTON` command tests the functionality of the device's buttons.
|
||
|
It waits for the user to press and release a specified button in a designated timeout period.
|
||
|
|
||
|
The command required two input parameters:
|
||
|
* The first parameter specifies the expected button or combination of buttons, with possible values: LEFT, RIGHT, BOTH.
|
||
|
* The seconds parameter specifies the timeout duration in seconds in range 1 to 9
|
||
|
|
||
|
If the specified button or button combination is not detected within the timeout, the command will return and `ERROR TIMEOUT`.
|
||
|
|
||
|
Example (to wait for 9 seconds for the left button):
|
||
|
```
|
||
|
BUTTON LEFT 9
|
||
|
OK
|
||
|
```
|
||
|
|
||
|
### TOUCH
|
||
|
The `TOUCH` command test the functionality of the display's touch screen.
|
||
|
It draws a filled rectangle in one of the four display quadrants and waits for user interaction.
|
||
|
|
||
|
The command requires two input parameters:
|
||
|
|
||
|
* The first parameter, which should be a value between 0 and 3, determines the quadrant where the rectangle will be drawn.
|
||
|
* The second parameter, a value between 1 and 9, represents the timeout in seconds.
|
||
|
|
||
|
If the display is not touched within the specified timeout, the command will return an `ERROR TIMEOUT`.
|
||
|
|
||
|
Example (to draw a rectangle in the top-left quadrant and wait for 9 seconds for touch input):
|
||
|
```
|
||
|
TOUCH 0 9
|
||
|
OK 50 90
|
||
|
```
|
||
|
|
||
|
### SENS
|
||
|
The `SENS` command is used to evaluating the touch screen sensitivity.
|
||
|
It draws a filled box around the touch coordinates.
|
||
|
It takes one input parameter, a sensitivity, a decimal value representing sensitivity.
|
||
|
Please note that the sensitivity value is model-dependent.
|
||
|
|
||
|
It's important to mention that this command does not return any output.
|
||
|
A device restart is required to stop this operation.
|
||
|
|
||
|
Example:
|
||
|
```
|
||
|
SENS 12
|
||
|
```
|
||
|
|
||
|
### PWM
|
||
|
The `PWM` command sets the display backlight using PWM (Pulse Width Modulation).
|
||
|
This command takes one input parameter, a decimal value between 0 to 255, and adjusts the PWM output to control the display LED backlight.
|
||
|
|
||
|
Example::
|
||
|
```
|
||
|
DISP 128
|
||
|
OK
|
||
|
```
|
||
|
|
||
|
### SD
|
||
|
The `SD` command initiates a simple test of the SD card.
|
||
|
The test includes writing and reading back a few blocks of data and comparing them for equality.
|
||
|
|
||
|
Possible error return codes are:
|
||
|
|
||
|
- `ERROR NOCARD` - Indicates that no SD card is present
|
||
|
- `ERROR sdcard_write_blocks (n)` - Indicates a write failure to the N-th block
|
||
|
- `ERROR sdcard_read_blocks (n)` - Indicates a read failure from the N-th block
|
||
|
- `ERROR DATA MISMATCH` - Indicates a mismatch between the read data and the written data
|
||
|
- `OK` - Indicates that the test has passed successfully
|
||
|
|
||
|
Note: the command returns `UNKNOWN` for models without the SD card support
|
||
|
|
||
|
Example:
|
||
|
```
|
||
|
SD
|
||
|
OK
|
||
|
```
|
||
|
|
||
|
### SBU
|
||
|
The `SBU` command allows you to set the states of SBU1 and SBU2 pins.
|
||
|
It takes two input parameters, each representing the state of one pin (0 or 1), and sets the corresponding output pins accordingly.
|
||
|
|
||
|
Example:
|
||
|
```
|
||
|
// sets SBU1 <- 1, SBU2 <- 0
|
||
|
|
||
|
SBU 1 0
|
||
|
OK
|
||
|
```
|
||
|
|
||
|
### OTP READ
|
||
|
The `OTP READ` command is utilized to retrieve a string parameter from the device's OTP memory.
|
||
|
This string typically contains information identifying the model and production batch of the device.
|
||
|
The command always returns OK followed by the read value.
|
||
|
If the OTP memory has not been written yet, it returns a special response: OK (null).
|
||
|
|
||
|
Example:
|
||
|
```
|
||
|
OTP READ
|
||
|
OK (null)
|
||
|
```
|
||
|
|
||
|
### OTP WRITE
|
||
|
The `OTP WRITE` command enables you to store a string parameter (which can be used to identify the model and production batch, for instance) into the device's OTP memory.
|
||
|
The parameter can be up to 31 characters in length.
|
||
|
|
||
|
Example:
|
||
|
```
|
||
|
OTP WRITE 10002
|
||
|
OK
|
||
|
```
|
||
|
|
||
|
### VARIANT
|
||
|
The `VARIANT` command allows you to write up to 32 decimal values (representing device variant options), each ranging from 0 to 255, and delimited by spaces, into the OTP memory.
|
||
|
|
||
|
Example (to write 8 bytes into OTP memory):
|
||
|
```
|
||
|
VARIANT 128 64 100 1 2 3 0 0
|
||
|
```
|
||
|
|
||
|
### WIPE
|
||
|
This command invalidates the current firmware in the flash memory by erasing its beginning, including metadata.
|
||
|
After performing this operation, it displays the text "WIPED" on the screen and returns the response OK.
|
||
|
|
||
|
Example:
|
||
|
```
|
||
|
WIPE
|
||
|
OK
|
||
|
```
|
||
|
|
||
|
### OPTIGAID READ
|
||
|
TBD
|
||
|
|
||
|
### CERTINF READ
|
||
|
TBD
|
||
|
|
||
|
### CERTDEV WRITE
|
||
|
TBD
|
||
|
|
||
|
### CERTDEV READ
|
||
|
TBD
|
||
|
|
||
|
### CERTFIDO WRITE
|
||
|
TBD
|
||
|
|
||
|
### CERTFIDO READ
|
||
|
TBD
|
||
|
|
||
|
### KEYFIDO WRITE
|
||
|
TBD
|
||
|
|
||
|
### KEYFIDO READ
|
||
|
TBD
|
||
|
|
||
|
### LOCK
|
||
|
TBD
|
||
|
|
||
|
### CHECK LOCKED
|
||
|
TBD
|
||
|
|