Binary Commands

ProffieOS v6.7x010

Binary Commands

---

Protocol Overview

To put the board in Binary Communication mode SEND following ASCII command:

openSession\n

The board will respond with:

Opening Session…\n

Wait > 500 ms and discard the bytes read, as other modules could begin status transmission on serial until the session is properly locked.

Protocol safety error layer

Every transaction of bytes in binary mode must be wrapped in this manner.

Dir	Field	Size [offset]	Description
🔻	S_TransactionID	2 [0]	Transaction ID decided by the sender
🔻	S_DataPacketLen	2 [2]	Size of DataPacket (max 1044)
🔻	S_ErrorFlags	2 [4]	Error Flags
🔻	S_DataPacket	N [6]	Command sent data
🔻	S_CRC	4 [N+6]	CRC calculated from offset [0] : [N+6]
▲	R_TransactionID	2 [0]	S_TransactionID
▲	R_DataPacketLen	2 [2]	Size of DataPacket (max 1044)
▲	R_ErrorFlags	2 [4]	Error Flags
▲	R_DataPacket	N [6]	Command received data
▲	R_CRC	4 [N+6]	CRC calculated from offset [0] : [N+6]

Dir: 🔻 = Host to Board. ▲ = Board to Host

Safety Layer Error Flags (16 bit field)

Bit	Error	Description
16	Header	Received < 6 bytes and could not determine how many bytes the packet should have and wait
15	Data Length	Incoming package with too many bytes
14	Received Data timeout	Timeout on received data
13	CRC	Transaction corrupted, CRC32 does not match

The following commands are available and represent the content of S_DataPacket for 🔻 and R_DataPacket for ▲ from the protocol safety layer.

Session Control Commands

• Hello
• Unlock
• Bye

Device Control Commands

• Reset (Not implemented yet)
• Get Errors (Not implemented yet)

Memory Management Commands

• Info
• Format
• Get Dir Files
• Remove File/Folder
• Remove Files

Memory Access Commands

• Open Read
• File Read
• Open Write
• File Write
• File Close
• File CRC

---

Session Control Commands

0x0_ Commands to control a binary communication session

Hello Command

Gets device identification and initiates communication session

Dir	Field	Size [offset]	Description
🔻	CommandID	1 [0]	0x01
▲	Error	1 [0]	Command error
▲	HardwareID	4 [1]	HW id : bit 31-24 ( 8 bits , 0 – UltraProffie Zero , 1 – UltraProffie Lite) Audio : bit 23- 20 (4 bits, 0 – 2W, 1 – 3W) Charger: bit 19- 17 (3 bits, 0 – None , 1 - 1A) Sensor: bit 16 – 14 (3 bits, 0 - LSM) Protection: bit 13 (1 bit, 0/1 ) CPU: bit 12-10(3 bit, 0- stm32l431c8)
▲	SerialNumber	4 [5]	Serial number (uint32)
▲	ErrorCount	2 [9]	Number of errors logged in RAM
▲	RxBufferSize	2 [11]	Size of receiver buffer [bytes]
▲	TxBufferSize	2 [13]	Size of transmitter buffer [bytes]
▲	LockState	1 [15]	1 = locked, 0 = unlocked
▲	SysTick	4 [16]	System Tick

Dir: 🔻 = Host to Board. ▲ = Board to Host

Unlock Command

Unlock communication session. Before receiving this, all commands except “Hello” and “Bye” are not executed

Dir	Field	Size [offset]	Description
🔻	CommandID	1 [0]	0x02
🔻	Random	4 [1]	For future use, data sent is unused for now
🔻	RandomCheck	4 [5]	For future use, data sent is unused for now
▲	Error	1 [0]	Command error
▲	OldLockState	1 [1]	Lock state before command (1 / 0)
▲	NewLockState	1 [2]	Lock state after command (1 / 0)

Dir: 🔻 = Host to Board. ▲ = Board to Host

Bye Command

Ends communication session and resumes effects. To start a binary communication session, host will have to issue ”openSession” (ASCII) , “Hello” and “Unlock” commands.

Dir	Field	Size [offset]	Description
🔻	CommandID	1 [0]	0x03
▲	Error	1 [0]	Command error

Dir: 🔻 = Host to Board. ▲ = Board to Host

---

Device Commands

0x2_ General device control commands

Reset Command

!!! Not implemented yet
Reset the board

Dir	Field	Size [offset]	Description
🔻	CommandID	1 [0]	0x20
▲	Error	1 [0]	Command error

Dir: 🔻 = Host to Board. ▲ = Board to Host

Get Errors Command

!!! Not implemented yet
Get errors - to be defined later, draft definition bellow

Dir	Field	Size [offset]	Description
🔻	CommandID	1 [0]	0x21
🔻	MaxErrors	2 [1]	Maximum number of errors to be reported (must fit the Tx buffer size: each error takes 5 bytes
▲	Error	1 [0]	Command error
▲	RepErrors	2 [1]	Number of errors that are reported in the Errors field (≤ MaxErrors)
▲	UnrepErrors	2 [3]	Number of errors that remain unreported = actual number of errors - RepErrors
▲	Errors	0...5 * RepErrors [5]	5 bytes per error: 4 bytes = SystemTick (number of [ms] from start); 1 byte = error code Command Error Dictionary

Dir: 🔻 = Host to Board. ▲ = Board to Host

---

Memory Management Commands

0x4_ Memory management commands

File System Info Command

Returns File System information

Dir	Field	Size [offset]	Description
🔻	CommandID	1 [0]	0x40
▲	Error	1 [0]	Command error
▲	InitialMounted	1 [1]	1 if disk was already mounted , 0 otherwise
▲	Mounted	1 [2]	1 if disk mounted successfully, 0 otherwise
▲	DiskSize	8 [3]	Disk size in bytes
▲	UsedBytes	8 [11]	Used bytes from disk
▲	BlockSize	8 [19]	Default 512
▲	PageSize	8 [27]	Default 0
▲	maxOpenFiles	8 [35]	Default 16 (we only use 1 open file at a time)
▲	maxPathLen	8 [43]	Max path length (default 256)

Dir: 🔻 = Host to Board. ▲ = Board to Host

Format Command

Format disk (storage memory)

Dir	Field	Size [offset]	Description
🔻	CommandID	1 [0]	0x41
▲	Error	1 [0]	Command error
▲	Result	1 [1]	0 success, error otherwise

Dir: 🔻 = Host to Board. ▲ = Board to Host

Get Dir Files Command

Return the folders and files from received path, a null terminated string (e.g. path = “/\0” returns the folders and files from root path; path = “default\0” returns the files and folders from "default" folder)

Dir	Field	Size [offset]	Description
🔻	CommandID	1 [0]	0x42
🔻	PageNr	1 [1]	Default 1, if page is out of range returns first page
🔻	Path	n [2]	Null terminated string path (n - size of path string, max 256 bytes)
▲	Error	1 [0]	Command error
▲	PageNr	1 [1]	Returned page number (can be different from requested - if requested out of range)
▲	TotalPages	1 [2]	Number of total pages
▲	NrOfEntries	1 [3]	Number of entries returned (on current page)
▲	Name	n [4]	Name of file/folder null terminated (\0)
▲	Attribute	1 [4+n]	Attribute flags for entry (READONLY 0x01; HIDDEN 0x02; SYSTEM 0x04; VOLUME 0x08; DIR/Folder 0x10; ARC/File 0x20)
▲	Size	4 [5+n]	File/folder size in bytes (folder size is reported as 0)
▲	...	...	...
▲	Name	nx [4 + (nN + 5) * (NrOfEntries - 1)]	- each entry occupies a different nN size for name (null terminated), 1 attribute and 4 size bytes ...
▲	Attribute	1 [...]	...
▲	Size	4 [...]	...

Dir: 🔻 = Host to Board. ▲ = Board to Host

Remove Command

Deletes a file or an empty folder (folder must be empty to remove; first remove its children, then the folder)

Dir	Field	Size [offset]	Description
🔻	CommandID	1 [0]	0x43
🔻	Path	n [1]	Null terminated string path (n - size of path string, max 256 bytes)
▲	Error	1 [0]	Command error
▲	Result	1 [1]	1 success, 0 fail
▲	Attribute	1 [2]	Attribute flags of deleted path file/folder (READONLY 0x01; HIDDEN 0x02; SYSTEM 0x04; VOLUME 0x08; DIR/Folder 0x10; ARC/File 0x20)

Dir: 🔻 = Host to Board. ▲ = Board to Host

Remove Files Command

Deletes all files from a folder (first level only, no recursion)

Dir	Field	Size [offset]	Description
🔻	CommandID	1 [0]	0x43
🔻	Path	n [1]	Null terminated string path (n - size of path string, max 256 bytes)
▲	Error	1 [0]	Command error
▲	NrFiles	2 [1]	Number of removed/deleted files
▲	Result	1 [3]	1 success, 0 fail

Dir: 🔻 = Host to Board. ▲ = Board to Host

---

Memory Access Commands

0x5_ Memory access commands

Open Read Command

Open a file for reading

Dir	Field	Size [offset]	Description
🔻	CommandID	1 [0]	0x50
🔻	Path	n [1]	Null terminated string path (n - size of path string, max 256 bytes; e.g. "defaultFont/blast01.waw\0")
▲	Error	1 [0]	Command error
▲	FileSize	4 [1]	File size in bytes

Dir: 🔻 = Host to Board. ▲ = Board to Host

File Read Command

Read from an opened for reading file

Dir	Field	Size [offset]	Description
🔻	CommandID	1 [0]	0x53
🔻	NrReqBytes	2 [1]	Number of requested bytes to be read from the current offset (currently max 1024)
🔻	OffsetInFile	4 [3]	Relative offset in current file from where to read
▲	Error	1 [0]	Command error
▲	NrReadBytes	2 [1]	Number of bytes read
▲	CurrentOffset	4 [3]	Current file position reached after read command
▲	DataContent	NrReadBytes [7]	Actual file data content

Dir: 🔻 = Host to Board. ▲ = Board to Host

Open Write Command

Open a file for writing, if it doesn't exist it creates it and it’s necessary path (e.g. path = “defaultFont/blast01.wav” creates a folder named "defaultFont" and in it creates a file named "blast01.wav")

Dir	Field	Size [offset]	Description
🔻	CommandID	1 [0]	0x51
🔻	Path	n [1]	Null terminated string path (n - size of path string, max 256 bytes; e.g. "defaultFont/blast01.waw\0")
▲	Error	1 [0]	Command error

Dir: 🔻 = Host to Board. ▲ = Board to Host

File Write Command

Write data content in an opened for write file

Dir	Field	Size [offset]	Description
🔻	CommandID	1 [0]	0x52
🔻	OffsetInFile	4 [1]	Relative offset where to write in current file (set to 0xFFFFFFFF to ignore the offset and write at current offset)
🔻	NrBytesToWrite	2 [5]	Number of bytes to write (currently max 1024)
🔻	DataContent	NrBytesToWrite [7]	Actual data content to write to file
▲	Error	1 [0]	Command error
▲	CurrentOffset	4 [1]	Current file position reached after the write operation
▲	NrBytesWritten	2 [5]	Actual number of written bytes

Dir: 🔻 = Host to Board. ▲ = Board to Host

File Close Command

Close currently opened file (for write or for read)

Dir	Field	Size [offset]	Description
🔻	CommandID	1 [0]	0x54
▲	Error	1 [0]	Command error

Dir: 🔻 = Host to Board. ▲ = Board to Host

File CRC Command

Calculate CRC32 of a file; does not require the file to be opened

Dir	Field	Size [offset]	Description
🔻	CommandID	1 [0]	0x55
🔻	Path	n [1]	Null terminated string path (n - size of path string, max 256 bytes; e.g. "defaultFont/blast01.waw\0")
▲	Error	1 [0]	Command error
▲	CRC32	4 [1]	Calculated CRC32

Dir: 🔻 = Host to Board. ▲ = Board to Host

---

Error Dictionary

(work in progress)

Value	Error	Description
0x00	trOK	All good – transaction OK
0x01	trOpenFirst	A read or write command was issued without previously opening a file for writing or reading
0x02	trAlreadyOpen	A file is currently opened
0x03	trNothingToClose	A close file operation was initiated, but there is no opened file
0x04	trPathAttillegalOperation	Illegal operation, can not make requested operation on path attribute (ex : trying to list/remove all files and the path is not a folder; trying to remove a path and the path is not a file or a folder)
0x05	trPathNotFound	Received Path not found
0xFD	trLocked	Session is locked, need to unlock first
0xFE	trUnknown	Unknown Command
0xFF	trFail	Command execution failed

---

(C) RSX Engineering SRL. FileVer. 1.1 / Apr. 2023