How It Works¶

This section provides more detail about the TROPIC01 Util ecosystem — the USB DevKit firmware and the Python CLI application.

Old USB DevKit Firmware¶

Before diving into the new firmware, here's how the old firmware works to illustrate what has changed:

• The USB DevKit accepts ASCII (human-readable) commands and returns ASCII responses. The commands are not wrapped in any frame protocol other than the USB-CDC transfer protocol.
• The USB DevKit acts only as a USB-to-SPI master converter (the STM32U5 talks to the TROPIC01 slave SPI interface) or as an executor of low-level operations (e.g. changing the SPI frequency or reading the TROPIC01 GPO pin).

New USB DevKit Firmware¶

The new firmware was developed to leverage the rich hardware of the STM32U5 microcontroller (used in Trezor HW wallets, among others), which offers up to 512 KiB of Flash memory and extensive cryptographic and security features. While the current version may not yet utilize every capability, it lays the groundwork for future expansion.

• The USB DevKit implements a command-response protocol — it accepts either raw commands (RawCmd) or application commands (AppCmd), and returns raw (RawResp), application (AppResp), or error responses (ErrorResp). Both types of commands use binary format rather than ASCII.
  • Error responses (omitted from the image for the sake of clarity) are returned when some error occurs before the USB DevKit can know which command (raw or application) it received.
• Raw commands are designed to provide the same capabilities as the old firmware did.
• Application commands are issued through the Python CLI (TROPIC01 Util) and allow us to perform more complex operations:
  • Libtropic with STM32U5xx HAL is built into the STM32U5 firmware, exposing the entire Libtropic API for communication with TROPIC01.
  • Using the STM32Cube HAL, the STM32U5's hardware can be interacted with.

Frame Protocol¶

The frames exchanged between the Host PC and the USB DevKit have the following format:

• Magic bytes are used to indicate where the frame starts. Their order depends on the direction of the frame (from or to the Host PC) to easily separate them when inspecting the raw communication.
• DATA_LEN field contains the length of the DATA field.
• DATA field contains RawCmd/AppCmd (Host PC -> USB DevKit) or RawResp/AppResp/ErrorResp (USB DevKit -> Host PC). All of these are encoded using Google's Protocol Buffers message format.
  • Commands are wrapped as UsbDevkitCmd messages and responses as UsbDevkitResp messages. This eliminates the need for a separate command ID field that would indicate, for example, whether the incoming message is AppCmd or RawCmd — that information is contained in the Protocol Buffers payload using the oneof feature.
• CRC16 field includes both DATA_LEN and DATA fields.

TROPIC01 Util¶

TROPIC01 Util is a Python CLI user application used to issue application commands to the USB DevKit. Raw commands are not supported, because they currently have no added value in the application context — they are primarily used by the Libtropic USB DevKit HAL.

TROPIC01 Util has its own commands, such as pin-set and pin-verify. These CLI commands can directly issue a single application command to the USB DevKit, but they can also issue multiple application commands and perform other actions on the Host PC. In other words, a single CLI command can perform multiple actions besides sending application commands.

See Use TROPIC01 Util for more information about how TROPIC01 Util is used.