Skip to content

Under the Hood

Jump to bottom
muzkr edited this page Nov 22, 2025 · 1 revision

Ichi virtualizes the radio as a USB drive, and reads/writes to files on this virtual disk are internally routed by Ichi to the corresponding physical memories.

The QS UV-K5 (V3) (and variants) contains two internal memories: MCU internal flash and SPI flash. The MCU internal memory stores the bootloader (e.g., Moto) and firmware. The SPI flash stores settings such as channel names and parameters.

The MCU's internal flash memory totals 128 KB, with the first 10 KB allocated to the bootloader and the remainder reserved for firmware (118 KB). Ichi adheres to the original bootloader partitioning scheme of 10 KB versus 118 KB.

               MCU internal flash
    0x08000000 +----------------+
               | Bootloader     | 10 KB
      08002800 +----------------+
               |                |
               | Firmware       | 118 KB
               :                :
               |                |
      08020000 +----------------+

The total capacity of the SPI flash is 2 MB. Utilization of the SPI flash space depends on the firmware. For example, the stock firmware has its own address scheme (where XX settings are stored at XX addresses), while third-party firmware may employ different address schemes. Some may even establish file systems on the SPI flash (such as FAT, LittleFS, etc.).

Ichi does not favor any specific use case. For Ichi, the SPI flash is simply a 2 MB plain binary file.

               SPI flash
    0x00000000 +----------------+
               |                |
               | Firmware       | 2 MB
               : specific       : 
               |                |
      00200000 +----------------+

As mentioned earlier, after connecting the radio to the computer via USB, Ichi will create a virtual disk. This disk (labeled ICHI) uses the FAT file system and is approximately 16 MB in size. Within the ICHI disk, two files (among others) are of particular interest:

  • BL.UF2 - This file contains the complete contents of the bootloader region within the MCU's internal flash memory, presented in UF2 format
  • DATA.UF2 - This file contains the complete contents of the SPI flash, presented in UF2 format

A UF2 file consists of a series of blocks, each 512 bytes in size, containing metadata and actual data (payload). Ichi requires each UF2 block to carry a 256-byte payload. Therefore, the UF2 file's payload efficiency is 50%, meaning the UF2 file size is twice the actual data size. Consequently, the BL.UF2 file size is 20 KB, while DATA.UF2 is 4 MB.

UF2 is a well-known and simple file format, with tools available for converting between UF2 and other file formats such as .bin, .elf, etc.

The above explains in detail Ichi's support for the "read" operation. The logic for write operations is slightly different, so let's proceed to that now.

Write Operations

BL.UF2 and DATA.UF2 are both read-only files, so you cannot expect to modify the bootloader or SPI flash by altering the contents of these files.

Ichi accepts writes in the form of UF2 files too - as you might expect.

As briefly mentioned earlier, the UF2 block contains both metadata and payload data. One piece of metadata is the payload's target address. Ichi uses this address to determine whether the data should be written to internal flash, SPI flash, or discarded altogether.

Therefore, structure the data you want to write into a UF2 file, set the metadata (target address) appropriately, and then copy (drag and drop) this file into the ICHI disk. That's it. Ichi will handle the rest.

Due to system resource constraints (primarily RAM), Ichi can accept a maximum of 256 KB of write data at a time. This poses no issue for the bootloader, as it remains well within the 256 KB limit.

As for SPI flash, it requires at least 8 write operations to completely overwrite the entire storage space (256 KB × 8 = 2 MB), for example:

               SPI flash
    0x00000000 +----------------+
               | Write #1       |
      00040000 +----------------+
               | Write #2       |
      00080000 +----------------+
               | Write #3       |
      000c0000 +----------------+  256 KB x 8 = 2 MB
               | Write #4       |
      00100000 +----------------+
               | Write #5       |
      00140000 +----------------+
               | Write #6       |
      00180000 +----------------+
               | Write #7       |
      001c0000 +----------------+
               | Write #8       |
      00200000 +----------------+

Please note that the diagram above represents only one possible scheme and does not imply that it is mandatory. For example, Ichi does not require that each data write must be exactly 256 KB in size, nor that the starting address must be aligned to a 256 KB boundary. In fact Ichi accepts non-contiguous UF2 blocks, that is, gaps may exist within the UF2 payload data. This provides significant flexibility for write operations!

However, there are indeed some restrictions, as listed below. Beyond that, the client party is completely unrestricted.

  • All blocks within a single UF2 file must target the same physical memory—either all internal flash (the bootloader) or all SPI flash
  • A single UF2 file can contains a maximum of 1024 blocks
  • The maximum payload size per block is 256 bytes
  • The target address of each block must be aligned to a 256-byte boundary, i.e., 0 == target address % 256

Additionally, only one file can be written at a time. Writing multiple files simultaneously will result in I/O errors.

Clone this wiki locally