With more and more new boards available and in wide use, and particularly also really powerful ones like ESP32, certain features of the boards should be queryable by the firmata host. Sometimes, new features for these boards are required for certain special use cases. Some of the features I'm thinking of involve:
Setting the ADC bit depth
Setting the PWM frequency
Query the input buffer size
Setting power states
etc.
It seems ugly to create new components and hence new main SYSEX commands for such simple tasks. This would not only unnecessarily use up the remaining numbers, it would also add complexity to the firmware. Instead, a single command should be used for setting/retrieving such "System Variables".
Set/Query System Variable command (used both directions)
0 START_SYSEX (0xF0)
1 SYSTEM_VARIABLES (0x66)
2 Operation (0 = query value, 1 = set value)
3 Data type (see below)
4 Status (0 = success, 1 = value is read-only, 2 = value is write-only, see below)
5..6 14 Bit variable ID
7 Pin number (if applicable, 0x7f otherwise)
8...n-1 Value, compressed (e.g. 5 bytes for an int32 field)
n END_SYSEX (0xF7)
To keep the implementation in the firmware simple, only few different data types will probably be supported.
Data type
0 Undefined (do not use)
1 A single Int32 value
Status
The status field is filled by the firmware to report the result of the operation.
Value
Name
Meaning when operation was "query"
Meaning when operation was "set"
0
Success
The value contains the queried data
The value contains the new value
1
Field is read-only
(never)
The value contains the existing value
2
Field is write-only
The operation failed, the value field is undefined
(never)
3
The data type is unknown
4
The Variable ID is unknown
5
Some other error (check log messages)
Each message from the host is answered, either with a success message or an error, except if the message is syntactically invalid (e.g. to few bytes)
Variable IDs
Value
Data Type
R/W
Description
0
Int
R
Function support check. Always returns 1
1
Int
R
Query maximum length of SYSEX message)
2
Int
R
Query input buffer size. When using network communication, systems with enough memory are typically able to handle multiple messages at once, but to avoid data loss, sending more data than indicated by this value will cause significant extra delay. Example: On the ESP32, the input buffer is typically 4kb, and SPI messages can be sent in chunks of 4kb. But after that, either a message requiring an ACK or a delay is required. Otherwise, a network retransmission is necessary, causing a significant performance drop.
-99
Reserved
100
Int
R/(W)
Set / Query ADC bit depth, per pin
101
Int
R/(W)
Set / Query PWM frequency, per pin
102
Int
(R)/W
Enter sleep mode after X seconds
103
Int
R/W
Set Sleep wakeup pin. The argument defines whether the wakeup on High (1) or low (0)
Note: Support for all commands except 0 is optional. Some values might be read-write on some boards, but readonly on others.
With more and more new boards available and in wide use, and particularly also really powerful ones like ESP32, certain features of the boards should be queryable by the firmata host. Sometimes, new features for these boards are required for certain special use cases. Some of the features I'm thinking of involve:
It seems ugly to create new components and hence new main SYSEX commands for such simple tasks. This would not only unnecessarily use up the remaining numbers, it would also add complexity to the firmware. Instead, a single command should be used for setting/retrieving such "System Variables".
Set/Query System Variable command (used both directions)
To keep the implementation in the firmware simple, only few different data types will probably be supported.
Data type
Status The status field is filled by the firmware to report the result of the operation.
Each message from the host is answered, either with a success message or an error, except if the message is syntactically invalid (e.g. to few bytes)
Variable IDs
Note: Support for all commands except 0 is optional. Some values might be read-write on some boards, but readonly on others.