standard data structures

[tehn]

introduce some commonly-used data structures with a clean, readable format

some modules use bit packing which generally means writing a custom decoder for these modules.

by establishing standard data structures we can abstract the types and introduce libraries which reuse code effectively.

[trentgill]

Below is not so much a suggestion, but a quick roundup of the low-level guts of current usage. I specifically haven't touched on bit-packed types as I don't remember the details off hand, and they are used in multiple different ways.

Currently used:

Of the modules I've surveyed the in-use types are:

• void (ie the lack of data, used for 'bang' style commands)
• s8: signed 8bit int
• u8: unsigned 8bit int
• s16: signed 16bit int
• u16: unsigned 16bit int

Multiple byte values are big-endian (ie. sent MSB first).

signed 16bit as voltage

This is a special case of the s16 integer, where it is used like a fract type representing the range -20..20 volts. There seems to be some inconsistency as to whether 1V = 1638, or 1638.3. The origin of these values is from Teletype's 14bit DAC converting the 0-10V range to 0..16383. This range is typically packed in an s16 (teletype's native data type), hence the extension of the range to -20..20

re: volt-per-octave representation this equates to an LSB step-size of 0.73 cents (or 0.61mV).

return values

Currently all the 8bit and 16bit values are acceptable as return values. Unlike leaders, followers can only respond with a single value of 1 or 2bytes.

Multiple return values would be a nice to have, but they would likely need to be fixed per command in order to keep leader reception relatively simple. ie. supporting send me all the items in list n would be a nightmare, but send me your x y z location could be useful for an accelerometer.

[ngwese]

another datatype which might be worth standardizing is representation of playback rate for audio playback or sequencer type devices. much like the signed 16bit as voltage some bipolar fractional value seems workable.

where this might come into play would be in #5 and #7 space.

[ngwese]

on the topic of multiple return values this pattern seemed vaguely related: https://www.i2c-bus.org/auto-increment/

[trentgill]

representation of playback rate

This would be great.

Relatedly, I'd love to see a standard representation of time which perhaps relates to #7. Perhaps this needs it's own topic though, as it is more than just a datatype. We could have an absolute time datatype (ms or seconds), but more interesting is time in a musical context (re: tempo).

https://www.i2c-bus.org/auto-increment/

This sounds to me like a stream more than a fixed type. That would be a really cool feature, though admittedly complicated, to add to the ii system. It's basically a type of arbitrary length where the implementation would be device specific, ie it wouldn't be able to be auto-generated like crow does. I've dreamed of streaming audio-files between W/ devices and this would be a way to add that.

[scanner-darkly]

"Unlike leaders, followers can only respond with a single value of 1 or 2bytes." doesn't the spec allow for an arbitrary number of bytes to be sent by followers? looks like libavr32/asf already supports it: https://github.com/monome/libavr32/blob/master/asf/avr32/drivers/twi/twi.c#L435

another good use case for this is requesting sequence data from followers.

[trentgill]

Indeed you are correct, I guess I meant no current devices support it at the ii level.

The big challenge for requesting multi-byte data of unknown length is the leader doesn't know how much memory to allocate. This gets complicated when you're trying to pass this data through an event queue.

I guess more generally, having arbitrary-sized data structures makes it difficult to implement things on embedded devices in particular.

[scanner-darkly]

we do have some of the current devices sending 16 bit values as 2 bytes, but yeah, length is specified by the leader.