[Feature] Adds support for METADATA for the spin board by luizvilla · Pull Request #157 · owntech-foundation/Core

luizvilla · 2026-07-29T14:37:56Z

Context

The spin board can hold information on its flash via the nvs driver in the OwnTech API. This can be leveraged to store important data onto the spin board indefinetly.

PR description

This pull request uses the nvs driver to write a certain number of parameters to the ship board in its NVS. These parameters can be used to store metadata. The current metadata stored is:

Metadata layout

All fields are stored under the BOARD_METADATA NVS category (0x0400).
Serial numbers and the shield password are stored as fixed-size raw ASCII
data without a null terminator. Version components and extra data are stored
as raw bytes.

Metadata field	NVS key	Stored format	Stored size	Set API	Get API
Spin serial number	`0x0400`	Raw ASCII	13 bytes	`setSpinSerialNumber()`	`getSpinSerialNumber()`
Shield serial number	`0x0401`	Raw ASCII	13 bytes	`setShieldSerialNumber()`	`getShieldSerialNumber()`
Spin hardware version	`0x0402`	Three `uint8_t` values: major, minor, revision	3 bytes	`setSpinVersion()`	`getSpinVersion()`
Shield hardware version	`0x0403`	Three `uint8_t` values: major, minor, revision	3 bytes	`setShieldVersion()`	`getShieldVersion()`
Shield password	`0x0404`	Raw ASCII, stored in plain text	3 bytes	`setShieldPassword()`	`getShieldPassword()`
Extra data slots 0–4	`0x0405`–`0x0409`	Opaque byte data	Up to 16 bytes per slot	`setExtraData()`	`getExtraData()`

Testing

This PR can be tested directly by checking out the branch metaData from Luiz Villa's fork:

https://github.com/luizvilla/Core/tree/metaData

You will be able to see that metaData and metaData_PR follow each other. the metaData branch only has the main.cpp implementation and the test_metadata_nvs.py test code.

Checklist of the planned commit sequence so an interrupted implementation can resume from where it stopped. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Adds a new NVS category for board/shield metadata (spin.metaData) and a nvs_storage_get_free_space() helper to measure remaining budget in the shared 4KB storage partition, since ADC calibration and safety thresholds already compete for that space. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Adds spin/shield serial numbers, spin/shield versions (major/minor/rev), a shield password, and 5 generic extra slots on top of the shared nvs_storage_store_data/retrieve_data API, following the same one-key-per- field pattern already used for ADC calibration and safety thresholds. Not yet wired into the public spin.metaData surface. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Wires the new MetaDataAPI class into SpinAPI following the same static- member composition pattern used for spin.data, spin.gpio, etc. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Ayoub-Farah

I have tested the code in https://github.com/luizvilla/Core/tree/metaData/src, here is the result after using the python file :

& C:\Users\afarahhass\AppData\Local\Programs\Python\Python312\python.exe `  .\src\test_metadata_nvs.py --port COM29                                
Using board 58435001004B001B on port COM29
[1/6] Clearing all metadata fields...
  CLEAR=OK
[2/6] Reading back (expect all fields empty/ERR)...
[3/6] Checking free NVS space (baseline)...
  FREE_SPACE=2008
[4/6] Writing canned test values...
[5/6] Reading back immediately (same-boot sanity check)...
  FIELD            WRITTEN          READ             RESULT
  SPIN_SERIAL      'SPIN000000001'  'SPIN000000001'  OK
  SHIELD_SERIAL    'SHLD000000001'  'SHLD000000001'  OK
  SPIN_VERSION     '9.9.9'          '9.9.9'          OK
  SHIELD_VERSION   '8.8.8'          '8.8.8'          OK
  SHIELD_PASSWORD  'abc'            'abc'            OK
  EXTRA_0          'EXTRA0'         'EXTRA0'         OK
  EXTRA_1          'EXTRA1'         'EXTRA1'         OK
  EXTRA_2          'EXTRA2'         'EXTRA2'         OK
  EXTRA_3          'EXTRA3'         'EXTRA3'         OK
  EXTRA_4          'EXTRA4'         'EXTRA4'         OK
[6/6] Resetting board and re-reading (persistence check)...
Traceback (most recent call last):
  File "C:\Users\afarahhass\Documents\Repo\CoreV2\Core_Luiz\src\test_metadata_nvs.py", line 468, in <module>
    sys.exit(main())
             ^^^^^^
  File "C:\Users\afarahhass\Documents\Repo\CoreV2\Core_Luiz\src\test_metadata_nvs.py", line 439, in main
    ser, port = reset_and_reconnect(port, board_id)
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\afarahhass\Documents\Repo\CoreV2\Core_Luiz\src\test_metadata_nvs.py", line 343, in reset_and_reconnect
    touch_reset(previous_port)
  File "C:\Users\afarahhass\Documents\Repo\CoreV2\Core_Luiz\src\test_metadata_nvs.py", line 243, in touch_reset
    reset_ser = serial.Serial(port, 1200, timeout=1)
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\afarahhass\AppData\Local\Programs\Python\Python312\Lib\site-packages\serial\serialwin32.py", line 33, in __init__
    super(Serial, self).__init__(*args, **kwargs)
  File "C:\Users\afarahhass\AppData\Local\Programs\Python\Python312\Lib\site-packages\serial\serialutil.py", line 244, in __init__
    self.open()
  File "C:\Users\afarahhass\AppData\Local\Programs\Python\Python312\Lib\site-packages\serial\serialwin32.py", line 80, in open
    self._reconfigure_port()
  File "C:\Users\afarahhass\AppData\Local\Programs\Python\Python312\Lib\site-packages\serial\serialwin32.py", line 222, in _reconfigure_port
    raise SerialException(
serial.serialutil.SerialException: Cannot configure port, something went wrong. Original message: OSError(22, 'Un périphérique qui n’existe pas a été spécifié.', None, 433)

It seems the test with metadata has been executed successfully, but the last test with the reset of the board has failed.

@Ayoub-Farah

setSpinSerialNumber, setShieldSerialNumber, and setShieldPassword trusted their fixed-length constants regardless of how much data the caller actually provided, so a shorter buffer (e.g. "ABC") caused nvs_storage_store_data to read past its end. Callers must now pass the buffer size explicitly, which is checked before touching NVS. Addresses review feedback from @Ayoub-Farah on PR owntech-foundation#157.

luizvilla · 2026-07-29T16:22:14Z

Updated the code. Got this result

luiz-villa@hp2-owntech:~/code/Core4$ /usr/bin/python3 /home/luiz-villa/code/Core4/src/test_metadata_nvs.py
Using board 423250070031003C on port /dev/ttyACM3
[1/8] Clearing all metadata fields...
  CLEAR=OK
[2/8] Reading back (expect all fields empty/ERR)...
[3/8] Attempting undersized writes (expect all rejected)...
  FIELD                    EXPECTED  ACTUAL  RESULT
  SPIN_SERIAL_BADSIZE      -2        -2      OK
  SHIELD_SERIAL_BADSIZE    -2        -2      OK
  SHIELD_PASSWORD_BADSIZE  -2        -2      OK
[4/8] Reading back (expect fields still empty/ERR)...
[5/8] Checking free NVS space (baseline)...
  FREE_SPACE=2008
[6/8] Writing canned test values...
[7/8] Reading back immediately (same-boot sanity check)...
  FIELD            WRITTEN          READ             RESULT
  SPIN_SERIAL      'SPIN000000001'  'SPIN000000001'  OK
  SHIELD_SERIAL    'SHLD000000001'  'SHLD000000001'  OK
  SPIN_VERSION     '9.9.9'          '9.9.9'          OK
  SHIELD_VERSION   '8.8.8'          '8.8.8'          OK
  SHIELD_PASSWORD  'abc'            'abc'            OK
  EXTRA_0          'EXTRA0'         'EXTRA0'         OK
  EXTRA_1          'EXTRA1'         'EXTRA1'         OK
  EXTRA_2          'EXTRA2'         'EXTRA2'         OK
  EXTRA_3          'EXTRA3'         'EXTRA3'         OK
  EXTRA_4          'EXTRA4'         'EXTRA4'         OK
[8/8] Resetting board and re-reading (persistence check)...
Done
  FIELD            WRITTEN          READ             RESULT
  SPIN_SERIAL      'SPIN000000001'  'SPIN000000001'  OK
  SHIELD_SERIAL    'SHLD000000001'  'SHLD000000001'  OK
  SPIN_VERSION     '9.9.9'          '9.9.9'          OK
  SHIELD_VERSION   '8.8.8'          '8.8.8'          OK
  SHIELD_PASSWORD  'abc'            'abc'            OK
  EXTRA_0          'EXTRA0'         'EXTRA0'         OK
  EXTRA_1          'EXTRA1'         'EXTRA1'         OK
  EXTRA_2          'EXTRA2'         'EXTRA2'         OK
  EXTRA_3          'EXTRA3'         'EXTRA3'         OK
  EXTRA_4          'EXTRA4'         'EXTRA4'         OK
PASS: values survived a board reset
[final] Checking free NVS space (post)...
  FREE_SPACE=1832
ALL CHECKS PASSED

luizvilla · 2026-07-29T16:23:57Z

Changes made. New test code available on the same branch as before.

Ayoub-Farah · 2026-07-29T16:48:31Z

test_metadata_nvs.py

It seems there is a problem on windows specifically with the python test file, so CODEX suggested the corrected file.

Using board 58435001004B001B on port COM29
[1/8] Clearing all metadata fields...
  CLEAR=OK
[2/8] Reading back (expect all fields empty/ERR)...
[3/8] Attempting undersized writes (expect all rejected)...
  FIELD                    EXPECTED  ACTUAL  RESULT
  SPIN_SERIAL_BADSIZE      -2        -2      OK
  SHIELD_SERIAL_BADSIZE    -2        -2      OK
  SHIELD_PASSWORD_BADSIZE  -2        -2      OK
[4/8] Reading back (expect fields still empty/ERR)...
[5/8] Checking free NVS space (baseline)...
  FREE_SPACE=2008
[6/8] Writing canned test values...
[7/8] Reading back immediately (same-boot sanity check)...
  FIELD            WRITTEN          READ             RESULT
  SPIN_SERIAL      'SPIN000000001'  'SPIN000000001'  OK
  SHIELD_SERIAL    'SHLD000000001'  'SHLD000000001'  OK
  SPIN_VERSION     '9.9.9'          '9.9.9'          OK
  SHIELD_VERSION   '8.8.8'          '8.8.8'          OK
  SHIELD_PASSWORD  'abc'            'abc'            OK
  EXTRA_0          'EXTRA0'         'EXTRA0'         OK
  EXTRA_1          'EXTRA1'         'EXTRA1'         OK
  EXTRA_2          'EXTRA2'         'EXTRA2'         OK
  EXTRA_3          'EXTRA3'         'EXTRA3'         OK
  EXTRA_4          'EXTRA4'         'EXTRA4'         OK
[8/8] Resetting board and re-reading (persistence check)...
Done
  FIELD            WRITTEN          READ             RESULT
  SPIN_SERIAL      'SPIN000000001'  'SPIN000000001'  OK
  SHIELD_SERIAL    'SHLD000000001'  'SHLD000000001'  OK
  SPIN_VERSION     '9.9.9'          '9.9.9'          OK
  SHIELD_VERSION   '8.8.8'          '8.8.8'          OK
  SHIELD_PASSWORD  'abc'            'abc'            OK
  EXTRA_0          'EXTRA0'         'EXTRA0'         OK
  EXTRA_1          'EXTRA1'         'EXTRA1'         OK
  EXTRA_2          'EXTRA2'         'EXTRA2'         OK
  EXTRA_3          'EXTRA3'         'EXTRA3'         OK
  EXTRA_4          'EXTRA4'         'EXTRA4'         OK
PASS: values survived a board reset
[final] Checking free NVS space (post)...
  FREE_SPACE=1832
ALL CHECKS PASSED

The test was a success, so it's good for me.

Ayoub-Farah

It's all ok for me

Luiz Villa and others added 4 commits July 29, 2026 16:27

Add metaData.md progress tracker for spin.metaData implementation

baae361

Checklist of the planned commit sequence so an interrupted implementation can resume from where it stopped. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

spin_api: expose MetaDataAPI as spin.metaData

4dd0869

Wires the new MetaDataAPI class into SpinAPI following the same static- member composition pattern used for spin.data, spin.gpio, etc. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

luizvilla requested a review from Ayoub-Farah July 29, 2026 14:37

luizvilla self-assigned this Jul 29, 2026

Ayoub-Farah requested changes Jul 29, 2026

View reviewed changes

Luiz Villa added 2 commits July 29, 2026 18:33

Removes the metaData.md from it

0144465

Adds the -2 return for the getExtraData function

61de6cc

Ayoub-Farah approved these changes Jul 29, 2026

View reviewed changes

luizvilla merged commit 7628c05 into owntech-foundation:main Jul 29, 2026
1 check passed

Navigation Menu

Uh oh!

[Feature] Adds support for METADATA for the spin board - #157

[Feature] Adds support for METADATA for the spin board#157
luizvilla merged 7 commits into
owntech-foundation:mainfrom
luizvilla:metaData_PR

luizvilla commented Jul 29, 2026

Uh oh!

Ayoub-Farah left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

luizvilla commented Jul 29, 2026

Uh oh!

luizvilla commented Jul 29, 2026

Uh oh!

Ayoub-Farah commented Jul 29, 2026

Uh oh!

Ayoub-Farah left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

luizvilla commented Jul 29, 2026

Context

PR description

Metadata layout

Testing

Uh oh!

Ayoub-Farah left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

luizvilla commented Jul 29, 2026

Uh oh!

luizvilla commented Jul 29, 2026

Uh oh!

Ayoub-Farah commented Jul 29, 2026

Uh oh!

Ayoub-Farah left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants