Glossary

Common terminology for phrases, words, and terms used throughout Beeton.

Thing

A 16-bit number representing the type of object being addressed.
From programming: like a class or type definition.
This is the main categorization of a device or object.
Example: light bulb vs smart plug

Instance

An 8-bit number representing a specific copy of a Thing.
From programming: like an object or instance.
Specifies which individual Thing is being targeted.
Example: light bulb 1 vs light bulb 2

Action

An 8-bit number indicating the specific action or event to trigger on a Thing.
From programming: like a function or method call.
This defines what you want the Thing to do.
Example: turn on vs set status

Payload

A sequence of bytes passed alongside the Action as additional data.
From programming: like function parameters or arguments.
Some actions may require no payload, while others depend on it.
Example:
- turn on → no payload needed
- set status → payload includes status value (true or false)

Thing Name

The human-readable name associated with a Thing ID.
Used for development and debugging; resolved from things.csv.

Action Name

The descriptive label for an Action ID.
Allows messages to be more legible during testing or logging.

Thing Table

The internal map on the Leader that links Thing IDs to their associated IP addresses.
Used for routing messages to the correct Joiner.

Joiner

A device that connects to the Leader to participate in the Beeton network.
Each Joiner may host one or more Things.

Leader

The central coordinator that stores the Thing table and relays messages.
Responsible for pairing, message forwarding, and persistence. Only one leader can be on the network.

HashMAC

A short hash of a Joiner’s MAC address used for identity and re-pairing.
Stored by both the Leader and the Joiner.

Reliable UDP

An internal feature of LightThread used by Beeton to guarantee message delivery with retries and ACKs.

Message Format

All Beeton messages follow this byte structure:

[Thing ID (2 bytes), Action ID (1 byte), Payload Length (2 bytes), Payload (0-65,535 bytes)]

• Thing ID → uint16_t, identifies the class of device
• Action ID → uint8_t, specifies the command
• Payload Length → uint8_t, number of bytes in payload
• Payload → custom byte data (0–255 bytes)

Example:
[0x0010, 0x03, 0x01, 0x01] → Light bulb, Set Status, 1 byte payload, value = true

Reserved and Invalid Values

Reserved Thing IDs

• 0xFFFF → Broadcast to all Things (may be restricted in practice)

Reserved Instance IDs

• 0xFF → May be used for "all instances" or broadcast per Thing (configurable)

Reserved Action IDs

• 0xFF → Reserved for custom/internal use

Invalid Values

• Any ID outside the expected size (Thing ID > 0xFFFF, Action ID > 0xFF) is ignored or triggers error
• Mismatched payload lengths (e.g. declared 3, sent 2) should be rejected