Firmware

Firmware

  • Firmware v3.0.4
    • default year for date: 1980
    • result code 0 on reading over file end (R command)
    • low-level USB device initializing also with I command
    • improved SPI handling
    • bugfix
      • missing result code on R command
  • Firmware v3.0.3
    • improved read/write speed to devices
    • updated result codes when file handle is incorrect
    • bugfix
      • data ready output was updated after complete processing of W, M, E commands
  • Firmware v3.0.2
    • bugfix
      • data ready output was only updated during receiving of data
  • Firmware v3.0.1
    • file handles are closed, when device is disconnected
    • J command without parameter gives device status (register 0)
    • bugfix
      • missing $ on response of find commands
      • R command without additional LF before size response
  • Firmware v3.0.0
    • first version

Communication Interface

The interface is configured during power up with the following pins within 10ms after reset.

  • PA7 - SPI MOSI (internal pulldown)
  • PA15 - SPI CS (internal pulldown)
  • PB3 - SPI SCK (internal pullup)

The interfaces have internal input and output buffers (each 8192 bytes) and can receive up to 4096 bytes, when the busy pin is low.

Bootloader (UART)

When the FATSC controller is started in bootloader mode then it automatically searches all available devices for a FIRMWARE.IMG file in the root directory. If a newer firmware version is found within 5s then an update will be done and the new firmware will be started (with interface selected by pin states). Always ensure that there is no power outage and it is also not allowed to reset the FATSC controller during the update process. The update can take up to 15s.

  • Pin states to select the interface:

    • PA7 MOSI = high
    • PA15 CS = low
  • UART settings:

    • Baud: 115200
    • Format: 8N1 (8 data bits, no parity bit, 1 stop bit)
    • BUSY output: high active (only send data when low)
  • Startup message (after max 1.3s):

    <LF>
    Bootloader<LF>
    Firmware v3.0.0<LF>
    !FF<LF>
    

UART

  • Pin states to select the interface:

    • PA7 MOSI = low
    • PA15 CS = low
    • PB3 SCK = high: 115200 baud, low: 9600 baud
  • UART settings:

    • Baud: 115200
    • Format: 8N1 (8 data bits, no parity bit, 1 stop bit)
    • BUSY output: high active (only send data when low)

I2C

planned feature - not implemented yet

  • Pin states to select the interface:

    • PA7 MOSI = low
    • PA15 CS = high
  • I2C settings:

    • Address: 0x52
    • Clock up to 400kHz
    • BUSY output: high active (only send data when low)
    • DATAREADY output: high active (data available when high)

SPI

  • Pin states to select the interface:

    • PA7 MOSI = high
    • PA15 CS = high
  • SPI settings:

    • MSB first
    • Mode 0: CPOL=0 (clock idle low), CPHA=0 (sample on the rising edge)
    • Clock up to 24MHz
    • 4us delay between data bytes
    • CS/SS low active
    • BUSY output: high active (only send data when low)
    • DATAREADY output: high active (data available when high)
  • Frame format:

    • Write:

      |_Pin__|__Type__|_Payload Size__|_________Payload_________|
      | MOSI | 0x01   |  LSB  |  MSB  | Byte 0 |  ...  | Byte N |
      | MISO | Ignore | Ready | Ready | Ready  | Ready | Ready  |
      
      • Set CS low before transmission start and set it high after the frame is sent completely.
      • If ready is zero then stop and start a new frame.
      • If ready is not zero then up to 4096 bytes can be received.
    • Read:

      |_Pin__|__Type__|_________Request Size__________|________Payload_________|
      | MOSI | 0x02   | Request LSB   | Request MSB   | 0x00   | 0x00 | 0x00   |
      | MISO | Ignore | Available LSB | Available MSB | Byte 0 | ...  | Byte N |
      
      • Set CS low before transmission start and set it high after the frame is sent completely.
      • If available bytes (16-bit) is zero then stop and do not send more bytes.
      • Only read up to available bytes.

Commands

Commands end with <LF> and numbers are written as strings of hexadecimal digits (ASCII), e.g. 16 would be 12 (bytes 0x31 and 0x32).

Carriage return <CR> is interpreted as line feed <LF> on commands.

Hexadecimal digits A to F must be upper case.

<LF> = 0x0A (line feed)
<CR> = 0x0D (carriage return)
<SP> = 0x20 (space)
{RR} = result code (hex value)

Startup message (after max 1.3s):

<LF>
 Storage Controller   <LF>
----------------------<LF>
 FATSC SoC Processor <LF>
!00<LF>

I - Initialize device

Mount the respective device and set the file listing (N command) to the root directory. The initializing process can take up to 5 seconds.

Command

I<SP>{D}<LF>
  • {D} drive name:
    • M: Memory card
    • U0: USB drive 0
    • U1: USB drive 1

Response

!{RR}<LF>
  • {RR}
    • 00 initializing and mounting successful
    • 02 incorrect parameters
    • 11 initializing or mounting failed
    • 60 EFC event/interrupt has occurred

K - Get free size

Get the free size in bytes of a mounted drive.

Command

K<SP>{D}<LF>
  • {D} drive name:
    • M: Memory card
    • U0: USB drive 0
    • U1: USB drive 1

Response

!{RR}<LF>
${XXXXXXXXXXXXXXXX}<LF>
!{RR}<LF>
  • {XXXXXXXXXXXXXXXX} free bytes (hex value)
  • {RR}
    • 00 command successful
    • 02 incorrect parameters
    • 03 command failed
    • 60 EFC event/interrupt has occurred

Q - Format drive

Format drive. Note, the format process cannot be aborted also not with an EFC event.

Command

Q<SP>CONFIRM FORMAT<SP>{D}<LF>
  • {D} drive name:
    • M: Memory card
    • U0: USB drive 0
    • U1: USB drive 1

Response

!{RR}<LF>
!{RR}<LF>
  • first response on start and second response when formatting is completed
  • {RR}
    • 00 format successful
    • 02 incorrect parameters
    • 03 format failed, check if device is read-only
    • 60 EFC event/interrupt has occurred

O - Open file

Open the respective file.

Command

O<SP>{H}{M}>{F}<LF>
  • {H} handle: 0...F
  • {M} mode: R=read, W=write, A=append (W and A will create the file if it does not exist)
  • {F} filename with path, e.g. “U0:/path/filename.txt”

Response

!{RR}<LF>
  • {RR}
    • 00 file opened successfully
    • 02 incorrect parameters
    • 03 command failed, write to read-only device
    • 20 file does not exist
    • 21 failed to open the file
    • 26 file name exists
    • 37 file handle in use
    • 60 EFC event/interrupt has occurred

C - Close file

Close the respective file.

Command

C<SP>{H}<LF>
  • {H} handle: 0...F

Response

!{RR}<LF>
  • {RR}
    • 00 file closed successfully
    • 02 incorrect parameters
    • 03 command failed, file not closed
    • 30 invalid file handle
    • 36 file handle does not open or is not in use
    • 60 EFC event/interrupt has occurred

R - Read file

Read data from file.

Command

R<SP>{H}{F}>{N}<LF>
  • {H} handle: 0...F
  • {F} filler byte
  • {N} bytes to read (hex value)

Response

!{RR}<LF>
Data-Bytes
${XXXXXXXX}<LF>
!{RR}<LF>
  • {XXXXXXXX} valid bytes without filler (hex value)
  • {RR}
    • 00 command successful
    • 02 incorrect parameters
    • 03 command failed
    • 36 file handle does not open or is not in use
    • 3A file handle requires read mode
    • 60 EFC event/interrupt has occurred

W - Write file

Write data to file.

Command

W<SP>{H}>{N}<LF>
  • {H} handle: 0...F
  • {N} bytes to write (hex value)

Response

!{RR}<LF>
Data-Bytes (from host)
${XXXXXXXX}<LF>
!{RR}<LF>
  • {XXXXXXXX} bytes written (hex value)
  • {RR}
    • 00 command successful
    • 02 incorrect parameters
    • 03 command failed
    • 36 file handle does not open or is not in use
    • 39 file handle requires write or append mode
    • 60 EFC event/interrupt has occurred

M - Copy from file to another file

This command copies data from one file to another file.

Command

M<SP>{S}<SP>{O}<SP>{D}<SP>{N}<LF>
  • {S} source handle: 0...F
  • {O} offset of source file (hex value)
  • {D} destination handle: 0...F
  • {N} bytes to copy (hex value)

Response

!{RR}<LF>
${XXXXXXXX}<LF>
!{RR}<LF>
  • {XXXXXXXX} bytes copied (hex value)
  • {RR}
    • 00 command successful
    • 02 incorrect parameters
    • 03 command failed
    • 23 offset value can only be within the file size
    • 31 source handle does not open
    • 32 destination handle does not open
    • 33 source handle requires read mode
    • 34 destination handle requires write or append mode
    • 60 EFC event/interrupt has occurred

F - Flush file

This command flushes the cached information of a writing file. The close command will also flush the data before closing the file.

Command

F<SP>{H}<LF>
  • {H} handle: 0...F

Response

!{RR}<LF>
  • {RR}
    • 00 command successful
    • 02 incorrect parameters
    • 03 command failed
    • 36 file handle does not open or is not in use
    • 60 EFC event/interrupt has occurred

P - File seek

Set the current byte position relative to the file start (0).

Command

P<SP>{H}>{N}<LF>
  • {H} handle: 0...F
  • {N} byte position (hex value)

Response

!{RR}<LF>
  • {RR}
    • 00 command successful
    • 02 incorrect parameters
    • 03 command failed
    • 22 seek only runs on files open for read
    • 23 position value can only be within the file size
    • 36 file handle does not open or is not in use
    • 60 EFC event/interrupt has occurred

Y - File tell

Get the current byte position from file start (0).

Command

Y<SP>{H}<LF>
  • {H} handle: 0...F

Response

!{RR}<LF>
${XXXXXXXX}<LF>
!{RR}<LF>
  • {XXXXXXXX} byte position (hex value)
  • {RR}
    • 00 command successful
    • 02 incorrect parameters
    • 36 file handle does not open or is not in use
    • 60 EFC event/interrupt has occurred

A - Rename file

Rename file.

Command

A<SP>{F}>{N}<LF>
  • {F} old filename with path, e.g. “U0:/path/filename.txt”
  • {N} new filename without path, e.g. “newname.txt”

Response

!{RR}<LF>
  • {RR}
    • 00 command successful
    • 02 incorrect parameters
    • 03 command failed
    • 60 EFC event/interrupt has occurred

D - Delete file/folder

Delete file or folder.

Command

D<SP>{F}<LF>
  • {F} filename or folder, e.g. “U0:/path/filename.txt”

Response

!{RR}<LF>
  • {RR}
    • 00 command successful
    • 02 incorrect parameters
    • 03 command failed
    • 20 file/folder does not exist
    • 60 EFC event/interrupt has occurred

? - Find file/folder

Find the respective file or folder.

Command

?<SP>{F}<LF>
  • {F} filename, e.g. “U0:/path/filename.txt”

Response

!{RR}<LF>
${XXXXXXXX}<LF>
${AA}<LF>
${HH:MM:SS MM-DD-YYYY}<LF>
!{RR}<LF>
  • {XXXXXXXX} size in bytes (hex value)
  • {AA} FAT attributes (hex value)
    • bit 7: reserved
    • bit 6: reserved
    • bit 5: archive
    • bit 4: folder
    • bit 3: volume id
    • bit 2: system
    • bit 1: hidden
    • bit 0: read-only
  • {HH:MM:SS MM-DD-YYYY} modified date and time
  • {RR}
    • 00 command successful
    • 02 incorrect parameters
    • 03 command failed
    • 20 file/folder does not exist
    • 60 EFC event/interrupt has occurred

@ - File listing

Start file and folder listing.

Command

@<SP>{F}<LF>
  • {F} folder/directory with path, e.g. “U0:/path/folder”

Response

!{RR}<LF>
  • {RR}
    • 00 command successful
    • 02 incorrect parameters
    • 03 command failed
    • 20 folder does not exist
    • 60 EFC event/interrupt has occurred

N - Next result

Get next result of file and folder listing.

Command

N<LF>

Response

!{RR}<LF>
{NAME}<LF>
${AA}<LF>
${XXXXXXXX}<LF>
!{RR}<LF>
  • {NAME} file/folder name
  • {AA} FAT attributes (hex value)
    • bit 7: reserved
    • bit 6: reserved
    • bit 5: archive
    • bit 4: folder
    • bit 3: volume id
    • bit 2: system
    • bit 1: hidden
    • bit 0: read-only
  • {XXXXXXXX} size in bytes (hex value)
  • {RR}
    • 00 command successful
    • 02 incorrect parameters
    • 03 command failed
    • 04 reached end of the file/folder list, this is not an error
    • 60 EFC event/interrupt has occurred

J - Get status

Read respective status register.

Command

J<SP>{N}<LF>
  • {N} register:
    • 0 device status, the reading can take up to 2 seconds
    • 1 file status
    • 2 auxiliary status

Response

!{RR}<LF>
${S}<LF>
!{RR}<LF>
  • {S} status (hex value)
    • 0 device status (8 bit)
      • bit 7: 0 reserved
      • bit 6: 1=U1 attached
      • bit 5: 1=U0 attached
      • bit 4: 1=M mounted
      • bit 3: 1=U1 mounted
      • bit 2: 1=U0 mounted
      • bit 1: 1=M readonly (WP=high)
      • bit 0: 1=M attached (CD=low)
    • 1 file status (16 bit)
      • bit 0: 1=handle 0 used … bit 15: 1=handle F used
    • 2 auxiliary status (16 bit)
      • bit 15-8: 0 reserved
      • bit 7: 1=auto mount on, if enabled there can be a response delay up to 1s, when a new USB device is connected
      • bit 6: 1=LSE okay (32768 Hz crystal)
      • bit 5: 1=HSE okay (high-speed external crystal)
      • bit 4: 1=EFC enabled
      • bit 3: 1=EFC triggered
      • bit 2: 1=EFC finished
      • bit 1: 1=stop state
      • bit 0: 0 reserved
  • {RR}
    • 00 command successful
    • 02 incorrect parameters
    • 60 EFC event/interrupt has occurred

Z - System control

Set system mode or registers.

Command

Z<SP>{N}{>{V}}<LF>
  • {N} register:
    • 0 start standby mode (without parameter), this will disable EFC and unmount all devices
    • 1 start stop mode (without parameter), this will disable EFC and unmount all devices
    • 2 wakeup pin function: 0=wakeup, 1=EFC (emergency flush and close), if EFC is triggered the current command will be aborted
    • 3 reboot
    • 4 0=auto mount off, 1=auto mount on (no mounting with I command needed), there can be a response delay up to 500ms, when a new USB device is connected
    • 5 SD WP overwrite: 0=off, 1=on
  • {V} parameter value, e.g. Z<SP>4>1<LF> to activate auto mounting

Response

!{RR}<LF>
  • {RR}
    • 00 command successful
    • 02 incorrect parameters
    • 60 EFC event/interrupt has occurred

G - Get time

Get the time and date.

Command

G<SP>{N}<LF>
  • {N} date or time:
    • D date
    • T time
    • G time and date

Response

{MM-DD-YYYY}<LF>
{HH:MM:SS}<LF>
{HH:MM:SS MM-DD-YYYY}<LF>
!{RR}<LF>
  • {MM-DD-YYYY} date D response
  • {HH:MM:SS} time T response
  • {HH:MM:SS MM-DD-YYYY} time and date G response
  • {RR}
    • 00 command successful
    • 02 incorrect parameters
    • 60 EFC event/interrupt has occurred

S - Set time

Set the time and date.

Command

S<SP>{DDDDTTTT}<LF>
  • {DDDDTTTT} date and time as 32 bit hex value or HH:MM:SS MM-DD-YYYY string
    • bit 31-25: years since 1980
    • bit 24-21: month (1-12)
    • bit 20-16: day (1-31)
    • bit 15-11: hour (0-23)
    • bit 10-5: minute (0-59)
    • bit 4-0: seconds divided by 2 (0-30)

Response

!{RR}<LF>
  • {RR}
    • 00 command successful
    • 02 incorrect parameters
    • 03 command failed
    • 60 EFC event/interrupt has occurred

T - Check RTC

The clock source of the RTC is automatically selected and this command checks the current RTC clock source.

Command

T<SP>{M}<LF>
  • {M} RTC mode:
    • S shared mode
    • B backup mode with crystal (LSE) and battery

Response

!{RR}<LF>
  • {RR}
    • 00 command successful, RTC mode is the requested one
    • 02 incorrect parameters
    • 03 command failed
    • 60 EFC event/interrupt has occurred

B - Set baudrate

Set the UART baud rate.

Command

B<SP>{N}<LF>
  • {N} baudrate as 32 bit hex value

Response

!{RR}<LF>
!{RR}<LF>
  • first result code with current baudrate and second code with new baudrate (after 10ms), if there are no errors
  • {RR}
    • 00 command successful
    • 02 incorrect parameters
    • 60 EFC event/interrupt has occurred

E - Speed test

Test read and write speeds of a mounted drive.

Command

E<SP>{D}>{S}<LF>
  • {D} drive name:
    • M: Memory card
    • U0: USB drive 0
    • U1: USB drive 1
  • {S} number of bytes to test (hex value)

Response

!{RR}<LF>
${AAAAAAAA}<LF>
${BBBBBBBB}<LF>
!{RR}<LF>
  • {AAAAAAAA} milliseconds of writing (hex value)
  • {BBBBBBBB} milliseconds of reading (hex value)
  • {RR}
    • 00 command successful
    • 02 incorrect parameters
    • 03 command failed
    • 60 EFC event/interrupt has occurred

V - Get version

Get the firmware version.

Command

V<LF>

Response

v{X.X.X}<LF>
!{RR}<LF>
  • v{X.X.X} version, eg. v3.0.0
  • {RR}
    • 00 command successful
    • 60 EFC event/interrupt has occurred

U - Update

Update the firmware with a subsequent restart. A downgrade to a lower version is not possible. Always ensure that there is no power outage and it is also not allowed to reset the FATSC controller during the update process. Please wait for a response code or after the reboot for the startup message. The update can take up to 15s and the interface is selected by pin states after the restart.

Command

U<SP>{F}<LF>
  • {F} filename with path, e.g. U0:/firmware.img

Response

!{RR}<LF>
  • {RR}

    • 03 programming error or checksum error, restart the device and try again
    • 21 file not found or incompatible file, check the file name and if the drive is initialized
  • on success startup message with result code 00:

    <LF>
     Storage Controller   <LF>
    ----------------------<LF>
     FATSC SoC Processor <LF>
    !00<LF>
    

<LF> - NOP

No operation (NOP).

Command

<LF>

Response

!00<LF>

Result Codes

CodeDescription
00OK, command successful
01Unknown command
02Incorrect parameters
03Operation failed, also returned on a write to a write-protected card
04Reached end of the file/folder list, this is not an error
11Initialize media/drive failed
12Not enough free space on media
20File/folder does not exist
21Failed to open the file
22Seek only runs on files open for read
23Position value can only be within the file size
26File/folder name already exists
30Invalid file handle
31Source file handle does not open
32Destination file handle does not open
33Source file handle requires read mode
34Destination file handle requires write or append mode
36File handle does not open
37File handle already in use
39File handle requires write or append mode
3AFile handle requires read mode
60An EFC event/interrupt has occurred