SRM Notes for 2026-10-01

[banchan86]

Agenda

• 🚀Small Issue (10 min)
• 🚅Medium Issue (20min)
• 🐢Large Issue (45min)

Reviewing Sync

• Documentation
  • Consider moving harp.schemaprocessor to harp.toolkit toolkit#31 (🚅)
  • Add device docs website device.behavior#40 (🚅)
• Hardware
  • https://github.com/aspaNeuro/aeon_vertigate (🚅)

[banchan86]

Notes from SRM:

Documentation

• API/Reference
  • Context
    • We discussed the API/Reference pages in the device-specific documentation pages, which are currently focused on automatically generated C# API documentation, and whether or not they are actually helpful.
  • Issues
    • One issue is that even the automatically generated C# documentation isn't all that helpful, as it contains a lot of cruft and you have to click through many layers to get to the actual information that you would find useful.
    • Another issue is that currently we actually have three different languages that are supposed to be covered in the reference: C#, Bonsai, and Python; if we wanted to go down the route of documenting the language APIs.
  • Proposal
    • On the other hand, maybe we don't actually need the language API documentation, but rather a device.yml documentation that would be useful regardless of language.
    • The key information that someone would be checking the reference for would be what registers are there, their address, properties, etc
    • Some of it is already fixed by the register table generated by harp-schema-processor (which is being ported over to harp.generators)
    • Each register would also have its own metadata card/page with stuff like the length, access, payload information, interfacetype, etc.
    • Most of the C# stuff can then be taken out, including the table of contents on the left sidebar, which can be replaced with a list of registers.
    • Everyone agreed that the current format needs work and that the proposed amendments would be helpful.
• Examples guide in docs
  • Context
    • The latest draft of the behavior docs has an "About These Examples" page at the top of the workflow section that explains the basic workflow logic for the examples.
    • This came about because of an observation that the instructions/bullets for the examples paradoxically contain too much duplicated information (e.g. insert keydowns -> createmessage -> send commands) and not enough meat (e.g. set this, set that without explaining why)
    • Expanding on them would be too repetitive, given that the examples were all pretty similar in shape, and the proposed article was supposed to solve that by front-loading the basic workflow logic and some detailed explanations.
  • Issues
    • Concerns were raised about the cost of maintenance and technical debt with duplicating content that could be centralized and pushed upstream to the main harp docs. We already do this with the Bonsai aspect of the docs, where we assume either a level of familiarity or redirect people to the main Bonsai docs.
    • On the other hand, there could be a viable middle ground where there is value in having a copy-pastable version of the basic workflow container, some short one-liners to explain the underlying concept which could be skimmed, then a signpost to the main harp docs for more.
    • We agreed that we should work on improving the conceptual documentation on the main harp website and see what gaps remain to be covered.
• Others
  • There was also a request to publish the device.yml alongside the docs so that other applications can consume it without pulling from GitHub, which sometimes requires authentication. This idea was accepted.

Hardware

• Aeon.Vertigate
  • This is a new device which uses micropython-microharp that is being migrated to the harp-tech CI/CD stack for building firmware and interfaces.
  • We discussed progress and issues around the migration, including python tooling, bootstrapping environments, and dependency management.
  • We also discussed consolidating individual device hardware tests to the harp toolkit verify utility so that we solve the problem once instead of for every device.