Naming things

[nebulous]

"There are only two problems in all of computer science: naming things, caching bugs, and off-by-one errors."

Almost 15 years ago a few of us started decoding the serial protocol used by our thermostats on a thread in cacoontech forums. Some of the placeholder terms used back then have carried forward through inertia and it's been a bit of a rock in my shoe recently.

We've used the term "register" due to some of the serial protocol's modbus influence. This is arguably ok, but we also use the terms "table" and "row" which come with relational baggage that doesn't apply and is a bit of an antipattern imo.

Each group of "registers" is organized by their top byte and the first "row" of said structure comes complete with a human readable name and (limited) self-description of the rest of the structure's contents. Hardly following a tabular structure, each "row" subsequently has wildly different lengths from the last. In places where repeating tabular structures do exist, they're within a given register, not across them.

I'd like to propose we adopt terminology which better-fits the observed data vs the placeholder terminology from an ancient forum post.

To me it seems like a heirarchy:

• device class (idu/odu/sam/nim/damper/etc)
  • First byte of "register" - a named category such as RLCSMAIN as determined by address 0x01 within
    • Second byte of "register" - a specific substructure containing fields (eg 0x04)
      • offsets within said structure (IEEE754 float at offset[8])

I think "device" works just fine for the top level. we'll just specify odu/idu/etc and if needed some subtype eg heat pump vs ac

What to call the top-level(née table)? ideas:

• namespace
• bank
• page
• object
• collection

What to call the next-level (née row)? ideas:

• record
• register
• entry
• member

Finally what to call individual variables identified within?

• field
• variable
• datapoint

---

I don't have strong opinions on this so I want to use terms others will be happy to adopt and ideally terms which will make sense to new users without an elaborate glossary. My favorites so far are probably device, collection, record, field but I'm open to better ideas.

thoughts?

[feisley]

I also think device, collection, record, field fits very nicely

They fit nicely with things like Device ID, Collection ID, Record ID as well as Field offset, length, type and so on.

[dragonflight]

So, I'm relatively new to this game having acquired my system in Dec '21. My googling skills failed me and I found no references to the protocol so I started with an oscilloscope and went from there. Only until I had the whole thing (well almost) figured out did I finally find everyone else! So I independently came up with tables, records, fields as I did not separate "registers" and devices, I then changed to registers to be consistent with everyone else. I have no problem with "tables" of different things (they are at least related). I wrote,drew and collected them together. I foresee problems with devices at the top though as there will be minor changes for different variants that will cause huge replications of subtrees. We may need to create a collection of records selected by record id (i.e. 0604), device id (51), device variant (xx) and a machine description - a list of device id,variant Each individual (except for really big installations) only actually need the three. I disagree (I would stay strongly, but I don't want to be too much of a twit) with Namespace, Bank and Page. Object is an overused buzzword that is meaningless in this context Collection is better, because that is what it is a grand collection of several disconnected bunches of semi-connected things Personally I like table (or even tables 1,2,3,4,6...) because that's how I think of them, how I can imagine them described in a manual, printed on a page. My 2 cents worth - in the end the only important thing is that we use common terms mike

…

On Mon, Jun 29, 2026 at 10:54 AM nebulous ***@***.***> wrote: "*There are only two problems in all of computer science: naming things, caching bugs, and off-by-one errors.*" Almost 15 years ago a few of us started decoding the serial protocol used by our thermostats on a thread in cacoontech forums. Some of the placeholder terms used back then have carried forward through inertia and it's been a bit of a rock in my shoe recently. We've used the term "register" due to some of the serial protocol's modbus influence. This is arguably ok, but we also use the terms "table" and "row" which come with relational baggage that doesn't apply and is a bit of an antipattern imo. Each group of "registers" is organized by their top byte and the first "row" of said structure comes complete with a human readable name and (limited) self-description of the rest of the structure's contents. Hardly following a tabular structure, each "row" subsequently has wildly different lengths from the last. In places where repeating tabular structures do exist, they're *within* a given register, not across them. I'd like to propose we adopt terminology which better-fits the observed data vs the placeholder terminology from an ancient forum post. To me it seems like a heirarchy: - device class (idu/odu/sam/nim/damper/etc) - First byte of "register" - a named category such as RLCSMAIN as determined by address 0x01 within - Second byte of "register" - a specific substructure containing fields (eg 0x04) - offsets within said structure (IEEE754 float at offset[8]) I think "device" works just fine for the top level. we'll just specify odu/idu/etc and if needed some subtype eg heat pump vs ac What to call the top-level(née table)? ideas: - namespace - bank - page - object - collection What to call the next-level (née row)? ideas: - record - register - entry - member Finally what to call individual variables identified within? - field - variable - datapoint ------------------------------ I don't have strong opinions on this so I want to use terms others will be happy to adopt and ideally terms which will make sense to new users without an elaborate glossary. My favorites so far are probably device, collection, record, field but I'm open to better ideas. thoughts? — Reply to this email directly, view it on GitHub <#223?email_source=notifications&email_token=AAEAXQM3XVE6LLZ3MADXD335CJ7LPA5CNFSNUABBM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63RPGEYDGMZZGY3TNJTSMVQXG33OVJZXKYTTMNZGSYTFMSSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAEAXQMLU3DRSCTE3F2WH7D5CJ7LPAVCNFSNUABGKJSXA33TNF2G64TZHM4DAMJWGM2TKO2ENFZWG5LTONUW63R3GEYDGMZZGY3TNILWAI> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/AAEAXQNTTJJFN3Z5P6JAU535CJ7LPA5CNFSNUABBM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63RPGEYDGMZZGY3TNJTSMVQXG33OVJZXKYTTMNZGSYTFMSSWK5TFNZ2KUZTPN52GK4S7NFXXG> and Android <https://github.com/notifications/mobile/android/AAEAXQI3RFAW2IHM2SIXRAD5CJ7LPA5CNFSNUABBM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63RPGEYDGMZZGY3TNJTSMVQXG33OVJZXKYTTMNZGSYTFMSSWK5TFNZ2K4ZTPN52GK4S7MFXGI4TPNFSA>. Download it today! You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[nebulous]

So collection seems like a winner for the named groups of records like RLCSMAIN. register still works as a shorthand for a combination of collection and record ie 0x0608. It is still the most commonly-spoken-about case and is backwardly compatible with historical conversations. Table is the only term I have a specific problem with, as to me table implies rows and columns and the data in this case is manifestly not that.