Concepts

Lifecycle and safety

The life of an instance

 create ─▶ InitializeAsync ─▶ ExecuteAsync ─▶ (stop) ─▶ DisposeAsync
               │                  │
        allocate resources    main loop; meanwhile:
                              OnSettingsChangedAsync, OnInputTimeout

Hook	When it runs
`InitializeAsync`	When the instance starts: allocate your resources here. An exception puts the instance into the `Faulted` state.
`ExecuteAsync(ct)`	The main loop. `ct` signals the stop. Returning early is allowed (passive Komod).
`OnSettingsChangedAsync`	When a setting changes, see Settings.
`OnInputTimeout(port)`	An input's deadline elapsed without a message.
`DisposeAsync`	On stop: release.

The instance states (Starting, Running, Faulted, Stopped) appear in the graph. If ExecuteAsync throws, the instance stops with an error, and the message is shown in the UI.

Status reporting

Context.ReportStatus(KomodHealth.Ok, "21.4 °C");
Context.ReportStatus(KomodHealth.Warning, "No data");

The status (Ok / Warning / Error) is shown on the node and the dashboard. This is the primary way for the user to see what is up with your Komod: give a short, human text.

Failsafe: the safe state

With an RC vehicle the worst case is that the control goes silent while the motor keeps running. Therefore:

Every input that affects an actuator should have a Deadline. When it elapses, OnInputTimeout should put the output into a neutral, safe state (throttle 0, heater off, rudder centered).
With hardware, register a failsafe (Context.Hardware.RegisterFailsafe): on stop and on a fault KOFA runs it first, then closes the device. See Hardware.
Emergency stop: a Trigger-typed estop input (Multiple = true) that latches until released is recommended.
Control from the browser should arrive continuously, repeated (e.g. 20 Hz), and be Deadline-guarded: if the browser disappears, the vehicle goes to a safe position. See UI input.

Warning

A Komod runs on the server as fully trusted code. A faulty or malicious package can damage the vehicle and the machine, so install only trusted packages, and test your own Komod on simulated hardware before you connect it to a real vehicle.

Development without hardware

On a development machine the hardware is simulated: every I2C address answers, the camera gives a test image, and Context.Hardware.IsSimulated is true. So your Komod can run without a real device.

Logging

Logger (ILogger) writes to KOFA's log, with the instance id. Report an error with LogError; an exception escaping from ExecuteAsync is logged by KOFA itself.