Examples Guide

This repo now treats examples as a staged ladder instead of a flat pile of one-off files.

Use this page as the chooser.

Start Here

Structure

  • examples/linux/i2c/raw/: raw Linux I2C transport examples
  • examples/linux/i2c/commissioning/: identity and readiness checks for known I2C devices
  • examples/linux/i2c/typed/: one simple typed read per supported product
  • examples/linux/i2c/advanced/: safe-by-default stateful workflows
  • examples/linux/uart/raw/: raw Linux UART transport examples with explicit line ownership
  • examples/linux/uart/commissioning/: UART bootstrap, identity, and readiness checks
  • examples/linux/uart/typed/: one simple typed read per supported product with explicit response-code bootstrap
  • examples/linux/uart/advanced/: safe-by-default UART workflows
  • src/ezo_arduino_*.hpp: shared Arduino helper headers used by the maintained sketches
  • examples/arduino/i2c/advanced/: broad bench-oriented Arduino I2C workflows, calibration, control, and compensation sketches
  • examples/arduino/uart/advanced/: focused Arduino UART admin, transport-switch, calibration-transfer, and routed-topology sketches
  • examples/arduino/i2c/: Arduino I2C smoke, inspect, typed, and advanced sketches
  • examples/arduino/uart/: Arduino UART smoke, inspect, typed, and focused advanced sketches

Safety Model

  • Linux advanced examples inspect first and only apply changes when --apply is present.
  • Linux advanced calibration examples use explicit --step= staging and bounded preview loops instead of open-ended polling or shells.
  • Linux calibration-transfer examples never import anything unless --apply and --payload=... are both present.
  • UART typed and advanced examples explicitly bootstrap response-code mode before assuming DATA + *OK success sequences.
  • Raw examples stay close to the transport layer and do not hide line ownership or synchronization.
  • Arduino advanced sketches stay explicit and hardware-facing; they do not reintroduce sequencer, shell, or scheduler abstractions.
  • Arduino mutation paths are controlled by top-of-file constants such as APPLY_CHANGES or APPLY_IMPORT instead of runtime shells or command parsers.

Linux Reference Matrix

Raw

Commissioning

Typed Reads

Advanced

Calibration

Product Workflows

Cross-Device Compensation

Shared Control and Transport

Arduino Matrix

Raw

Commissioning

Typed Reads

Advanced I2C

Advanced UART

Linux remains the full reference surface. Arduino is now broad and practical without mirroring every Linux advanced transport permutation: full raw/commissioning/typed coverage, a broad I2C bench-workflow layer, and a focused UART admin/routing layer.

Legacy Mapping

The _reference/ tree is retired. The table below records what survived as canonical guidance and what was intentionally dropped.

Legacy family Status Canonical replacement or rationale
_reference/Ezo_I2c_lib/Examples/I2c_lib_examples/EC_parsing_and_DO_compensation replaced in this phase examples/linux/i2c/advanced/do_salinity_comp_from_ec.c and examples/linux/uart/advanced/do_salinity_comp_from_ec.c keep the explicit EC-to-D.O. compensation chain without sequencer scaffolding.
_reference/Ezo_I2c_lib/Examples/I2c_lib_examples/temp_comp_example and temp_comp_rt_example replaced in this phase examples/linux/i2c/advanced/ec_temp_comp_from_rtd.c, examples/linux/uart/advanced/ec_temp_comp_from_rtd.c, and the Arduino I2C advanced sketch preserve RTD-driven EC compensation with explicit state ownership.
_reference/Ezo_I2c_lib/Examples/I2c_lib_examples/humidity_parsing superseded The typed HUM reads under examples/linux/*/typed/read_hum.c replace manual CSV destructuring with canonical typed helpers.
_reference/Ezo_I2c_lib/Examples/I2c_lib_examples/I2c_read_mulitple_circuits superseded The new cross-device advanced examples show explicit multi-device ownership without a sequencer abstraction.
_reference/Ezo_I2c_lib/Examples/I2c_lib_examples/i2c_scan_and_comms_example retired It is an interactive command-shell plus bus-discovery pattern, not canonical repo-level driver guidance. The repo now prefers explicit transport bring-up and commissioning examples instead of a baked-in console workflow.
_reference/Ezo_I2c_lib/Examples/I2c_lib_examples/iot_cmd_sample_code retired iot_cmd is a legacy shell framework. The canonical repo keeps transport-explicit examples and does not ship a command-console layer.
_reference/Ezo_uart_lib/Examples/Serial_port_expander_example replaced in this phase examples/arduino/uart/advanced/multi_device_router/multi_device_router.ino preserves the routed multi-device UART pattern without the old wrapper library or shell behavior.
_reference/Ezo_uart_lib/Examples/Serial_port_expander_tempcomp_example replaced in this phase The canonical router sketch plus the new compensation-chain examples cover the kept reusable behavior without port-expander-specific shell code.
_reference/Ezo_uart_lib/Examples/Arduino_mega_example and ESP32_sample_code superseded They were board-shaped variants of the routed UART pattern. The canonical router sketch replaces them with one maintained example and source-level board gating.
_reference/Ezo_I2c_lib/Examples/IOT_kits/** retired Wi-Fi kit application code is product-kit firmware, not portable driver guidance.
_reference/Ezo_I2c_lib/Examples/Projects/** retired Project application sketches are intentionally out of scope for the canonical driver repo.
_reference/Ezo_I2c_lib/Examples/Products/** retired Product-board app code is board-specific integration logic, not reusable library guidance.
_reference/Ezo_I2c_lib/Examples/Sequencer_lib_examples/** retired The sequencer examples demonstrate a legacy control framework that is antithetical to the current explicit library direction.
_reference/Ezo_I2c_lib/* and _reference/Ezo_uart_lib/* library sources retired The repo now ships one canonical library surface in src/; the legacy reference libraries are not a second maintained implementation.

Notes

  • I2C examples take device_path first and address second when those arguments are provided.
  • UART examples take device_path first and baud second when those arguments are provided.
  • Product-specific flags, when present, come after the transport arguments.
  • The calibration-transfer examples default to the pH product family for convenience. If you use another product, pass the correct transport/address combination yourself and override the product with --product=....