Skip to content

Objects & Data

Jump to bottom
NachtRave edited this page Aug 18, 2026 · 3 revisions

Objects & Data

Helioduino models a tracker as a set of identifiable objects connected through attachments and linkages.

The main object families are:

  • Actuators
  • Sensors
  • Panels
  • Power rails

Drivers and triggers are normally sub-objects attached to larger objects.

Object Identity

Each registered object has a HelioIdentity.

The identity records the object family, type, position index, string key, and hashed key used to find it again.

This lets saved configuration refer to a logical object without depending on a temporary C++ memory address.

Main Objects

HelioObject is the base for registered runtime objects.

It supplies common behavior for:

  • Identity
  • Shared-pointer access
  • Periodic updates
  • Low-memory handling
  • Linkages
  • Revision tracking
  • Serialization

Sub-Objects

HelioSubObject represents smaller control objects that belong to a parent.

Drivers and triggers are good examples.

A sub-object uses its parent for identity context and modified-state tracking rather than behaving like a completely independent top-level object.

Attachments

Attachments describe relationships between objects.

Examples include:

  • Panel → axis driver
  • Driver → movement actuator
  • Motor → position sensor
  • Motor → minimum and maximum trigger
  • Actuator → power rail
  • Actuator → parent panel
  • Panel → power-production sensor
  • Tracking panel → wind-speed sensor
  • Tracking panel → heating trigger
  • Tracking panel → storm trigger

These relationships can be unresolved and resolved again when configuration is loaded.

That is much safer for persistent configuration than storing raw pointer addresses.

Linkages

Linkages track which registered objects depend on each other.

They help the controller safely manage changes to the object graph and clean up relationships when an object is removed.

Revision Tracking

Persistent objects track a revision and modified state.

Changing a saved property marks the object as modified. A successful save clears that state.

This supports autosave without treating every update-cycle value as a configuration edit.

Runtime Objects and Data Objects

The code separates the active runtime object from the serializable representation.

Examples include:

  • HelioPanel and HelioPanelData
  • HelioActuator and HelioActuatorData
  • HelioSensor and HelioSensorData
  • HelioRail and HelioRailData

Runtime classes hold live control state and hardware relationships.

Data structures hold the persistent fields needed to reconstruct the object.

JSON and Binary

System and object data can be saved as:

  • JSON for readability
  • Binary for compactness

Supported storage depends on the fitted hardware.

EEPROM and SD are common local choices. Network-backed storage is an optional extension, not a requirement for tracker operation.

Calibration

Sensors and actuators can use HelioCalibrationData.

The calibration model is a linear transform:

y = A*x + B

Helpers can derive the transform from:

  • Two points
  • Two voltages
  • A known range
  • A known scale
  • A normal servo-style pulse range

This is particularly useful for axis-position sensors and actuators where the normalized electrical value needs to map to a physical angle or distance.

Keep Physical Meaning in the Correct Layer

A position sensor should be calibrated to a physical position before a driver uses it.

A driver should not contain a mystery offset that is actually compensating for a bad sensor calibration.

Panel axis offsets are a different concept. They describe installation or alignment geometry and belong to the panel.

Keeping calibration and geometry separate makes the tracker much easier to diagnose.

Brought to you by the generous support of our Patreons. Please consider a subscription if you find this software useful.

Clone this wiki locally