docs(prodtest): document prodtest protocol

[no changelog]

core/embed/prodtest/README.md

@@ -0,0 +1,232 @@
+# 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
+