Specify EEPROM data layout

[jonnew]

We need to document the layout for channel map EEPROM data. Currently, this is the layout:

ID	Address Range	Description
MAGIC	0x00 - 0x09	The ascii character string "open-ephys"
NAME	0x0A - 0x1D	ASCII character string specifying the name of the modules, padded out to 20 chars. e.g. "Hirose DF40 64 Ch. "[^1]
PCB_REV	0x1E	Single ASCII character indicating indicating PCB revision. e.g. 'A'
NUM_CHAN	0x1F	Single uint8_t specifying the number of channels in the channel map
CHAN_MAP	0x20 - 0x20 + NUM_CHAN	A uint8_t[NUM_CHAN] containing the channel map

I propose the following, revised layout:

ID	Address Range	Description
MAGIC	0x0000 - 0x0009	The ASCII character string "open-ephys"
LAOUT_VER	0x000A-0x000B	Major.Minor version number of the EEPROM layout (e.g. this specification will be 1.0)
NAME	0x000C - 0x002B	A null-terminated ASCII character string specifying the name of the module. Must be 32-bytes or shorter, including null terminator. e.g. "Hirose DF40 64 Ch.\0"
PCB_REV	0x002C	Single ASCII character indicating indicating PCB revision. e.g. 'A'
NUM_MAPS	0x002D	A single uint8_t specifying the number of maps
RESERVED	0x002E-0x03FF	Reserved
...
NUM_CHAN_0	0x0400	Single uint8_t specifying the number of channels in channel map 01
MAP_NAME_0	0x0401 - 0x420	A null-terminated ASCII character string specifying the name of channel map 0. Must be 32-bytes or shorter, including null terminator. e.g. "Headstage-64\0"
CHAN_MAP_0	0x0421 - 0x0421 + NUM_CHAN_0	A uint8_t[NUM_CHAN_0] containing channel map 0
...
NUM_CHAN_1	0x0800	Single uint8_t specifying the number of channels in channel map 11
MAP_NAME_0	0x0801 - 0x0820	A null-terminated ASCII character string specifying the name of channel map 1. Must be 32-bytes or shorter, including null terminator. e.g. "SPI Low Profile\0"
CHAN_MAP_1	0x0821 - 0x0821 + NUM_CHAN_1	A uint8_t[NUM_CHAN_1] containing channel map 1
...
NUM_CHAN_<NUM_MAPS - 1>	0x0400 * (NUM_MAPS - 1)	Single uint8_t specifying the number of channels in channel map NUM_MAPS - 11
MAP_NAME_<NUM_MAPS - 1>	0x0401 * (NUM_MAPS - 1) - 0x0420 * (NUM_MAPS - 1)	A null-terminated ASCII character string specifying the name of channel map NUM_MAPS - 1. Must be 32-bytes or shorter, including null terminator.
CHAN_MAP_<NUM_MAPS - 1>	0x0421 * (NUM_MAPS - 1) + 1 - 0x0421 * (NUM_MAPS - 1) + NUM_CHAN_<NUM_MAPS - 1>	A uint8_t[NUM_CHAN_<NUM_MAPS - 1>] containing channel map NUM_MAPS - 1

@filcarv and @aacuevas if you have additional ideas, corrections, or comments please document them here.

Footnotes

1. Must be 128 or less for this hardware, so this will fit into single byte. ↩ ↩² ↩³

[aacuevas]

I would move the EEPROM file version to just after the magic string. If the file format changes, it's useful to have the version in a position that is always going to be fixed no matter what.

The only other thing is that this format requires, at minimum, a 16Kb EEPROM. I usually prefer if the basic information (in this case, a single map) could be stored in a 2Kb EEPROM. This is a low-volume product, though, so this is mostly a non-issue.

[filcarv]

The current EEPROM being used is a 64Kbit (8KB EEPROM). It would be good if we could put the new memory map inside this 64Kbit.
If so, we are ready for production.

[jonnew]

Thanks for the feedback. @aacuevas I edited the table to account for your comment. @filcarv 8kB EEPROM will be able to hold 1 metadata block and 7 channel maps as each section takes 1 kB.

• I will implement this on https://github.com/open-ephys/ephys-test-module-hirose-df40-64-chan
• I will implement the reading side here
• Instead of the PCB version being displayed on the screen next to the NAME string, the currently selected map index will be displayed. This can be changed by long press on rotary encoder.

[jonnew]

I'm suggesting a couple of amendments above:

1. NAME is increased to 32 bytes. 20 was chosen because it fit on the OLED but that's not a good reason. Scroll text or ... can be used to display long strings and this choice should not be driven by the limitations of a piece of hardware
2. NAME now must include null terminator as the last byte of the string, padding data out is no long required.
3. Add MAP_NAME_X before NUM_CHAN_0 on each of the channel maps. This would be 32-bytes used to hold a nul-terminated string containing the name of the channel map.