SFP description

SFP (Simple Function Protocol) is a protocol designed to transfer function-like messages. One of the main advantages of the SFP is that it allows to send function messages encoded in ASCII or binary formats simultaneously over the same communication channel.

SFP Function

SFP Function is an abstraction which has a name (when transmitted in ASCII format) or an ID (when transmitted in binary format) and a list of arguments. The purpose of the SFP Function is to inform the target system to execute a specific function (described with a name and/or ID) with a particular list of arguments. Each function argument has a type, size (in bytes) and a value(s). Currently supported argument types are 32-bit integers and byte arrays.

ASCII format

In ASCII format only human readable ASCII characters (hex 0x20-0x7E, see ASCII table) are used to encode the SFP Function. This allows the user to simply type and execute target functions and read their output (if there is any) using nothing more than a terminal and a keyboard. Functions in ASCII format have the following structure: function name (consisting of only letters, numbers and underscore '_') followed by an open parenthesis, followed by a list or arguments (if there are any) separated with commas ',' and finished with a close parenthesis (see examples below).

The integer argument can be expressed in several forms:

• Decimal - simple decimal expression, e.g., 0, 1, 123, 99541.
• Hexadecimal - starts with '0x' followed by a hexadecimal value, e.g., 0x0, 0x01, 0x7B, 0x184D5.
• Binary - starts with '0b' followed by a binary value, e.g., 0b0, 0b0001, 0b01111011.
• Octal - starts with 0 followed by an octal value, e.g., 00, 01, 0173, 0302325.

The byte array argument is expressed as a list of integers, separated by commas and enclosed in brackets. The integer values should not exceed 255 (maximum byte value). Example: [0, 1, 85, 255, 0xFF, 0x99, 0b11]

ASCII format function examples: exampleFunction1(), example_Function2(123), example_function_3([0, 0x5F, 0x99, 123]), _4ExAmpleFunction_(965, [], [12, 037,95,0x95], 0b111). Note that there can be any number of space characters in between the arguments.

Binary format

Functions in binary format have the following structure:

• Header (1 byte, hex value 0xD4)
• Message length (2 bytes, MSB first)
• Function ID (1 byte)
• Argument1, argument2... (length-1 bytes).

As mentioned before, currently there are only two parameter types: 32-bit integer and 8-bit byte array, however to save memory footprint they can be encoded in few different ways.

• 0b00iiiiii - Small integer. The lower 6 header bits i define the integer value. Can store values from 0 to 63.
• 0b01ssssss [s bytes] - Small byte array. The lower 6 header bits s define the byte array size after which follows s number of bytes. Used for arrays, which are smaller than 64 bytes.
• 0b11000000 0xII - Integer (less than 2^8). The byte following after the header defines integer value I.
• 0b11000001 0xII 0xII - Integer (less than 2^16). The two bytes following after the header define integer value I (big-endian).
• 0b11000010 0xII 0xII 0xII - Integer (less than 2^24). The three bytes following after the header define integer value I (big-endian).
• 0b11000011 0xII 0xII 0xII 0xII - Integer. The four bytes following after the header define integer value I (big-endian).
• 0b11000100 0xSS [S bytes] - Byte array. The byte following after the header defines the byte array size S after which follows S number of bytes. Used for arrays, which are smaller than 256 bytes.
• 0b11000101 0xSS 0xSS [S bytes] - Byte array. The two bytes following after the header define the byte array size S (big-endian) after which follows S number of bytes. Currently SFP does not support arrays, that are larger than 65 kilobytes.

Example binary function, with explanations below:
0xD4 0x00 0x12 0xA1 0x27 0xC1 0x01 0x23 0xC3 0xFF 0xFF 0xFF 0xFF 0x47 0x11 0x22 0x33 0x55 0x77 0xBB 0xDD

0xD4 0x00 0x12 0xA1 0x27 0xC1 0x01 0x23 0xC3 0xFF 0xFF 0xFF 0xFF 0x47 0x11 0x22 0x33 0x55 0x77 0xBB 0xDD
Packet header. Constant value 0xD4 marks the beginning of the packet.

0xD4 0x00 0x12 0xA1 0x27 0xC1 0x01 0x23 0xC3 0xFF 0xFF 0xFF 0xFF 0x47 0x11 0x22 0x33 0x55 0x77 0xBB 0xDD
Packet length. Decimal value 18 (1 function ID byte + 17 argument bytes).

0xD4 0x00 0x12 0xA1 0x27 0xC1 0x01 0x23 0xC3 0xFF 0xFF 0xFF 0xFF 0x47 0x11 0x22 0x33 0x55 0x77 0xBB 0xDD
SFP function ID.

0xD4 0x00 0x12 0xA1 0x27 0xC1 0x01 0x23 0xC3 0xFF 0xFF 0xFF 0xFF 0x47 0x11 0x22 0x33 0x55 0x77 0xBB 0xDD
First argument. Binary 0b00100111. First two bits mean integer represented in a short form. Decimal value 39.

0xD4 0x00 0x12 0xA1 0x27 0xC1 0x01 0x23 0xC3 0xFF 0xFF 0xFF 0xFF 0x47 0x11 0x22 0x33 0x55 0x77 0xBB 0xDD
Second argument. First byte 0xC1 (0b11000001) means integer represented in two byte form. The remaining two bytes are the integer value 0x0123 (decimal 291).

0xD4 0x00 0x12 0xA1 0x27 0xC1 0x01 0x23 0xC3 0xFF 0xFF 0xFF 0xFF 0x47 0x11 0x22 0x33 0x55 0x77 0xBB 0xDD
Third argument. First byte 0xC3 (0b11000011) means integer in full (4 byte) form. The following four bytes are the integer value 0xFFFFFFFF (decimal -1 or 4294967295 if converted to unsigned).

0xD4 0x00 0x12 0xA1 0x27 0xC1 0x01 0x23 0xC3 0xFF 0xFF 0xFF 0xFF 0x47 0x11 0x22 0x33 0x55 0x77 0xBB 0xDD
Fourth and the last argument. First byte 0x47 (0b01000111) means a byte aray represented in short form (first two MSB bits) and of size of 7 bytes (six LSB bits). The following seven data bytes are the byte array values.