nomyk-device-core

Public reference architecture for a connected plant-sensing device.

Nomyk is a plant hardware project built around durable embedded-systems ideas: sensor abstraction, calibration, telemetry modeling, local status feedback, and cloud data flow. This repository is a public, portfolio-friendly subset that explains those ideas without exposing private production firmware, endpoints, credentials, infrastructure, or dashboard code.

Architecture In 30 Seconds

flowchart LR
  Sensors[Plant sensors] --> Adapters[Hardware adapters]
  Adapters --> Calibration[Calibration]
  Calibration --> Telemetry[Telemetry model]
  Calibration --> Status[Status light]
  Telemetry --> Cloud[Cloud boundary]
  Cloud --> Config[Safe config]
  Config --> Calibration
  Config --> Status

Loading

The device reads physical sensors, hides hardware details behind adapters, normalizes raw values through calibration profiles, emits versioned telemetry, and reflects state locally through a prioritized LED status system. The cloud side is represented as a boundary so the public repo can show data-flow concepts without exposing private infrastructure.

Visual Walkthrough

The core device loop is intentionally simple: sample, calibrate, classify, indicate, and publish.

flowchart TD
  Wake[Wake or scheduled tick] --> Sample[Sample sensors]
  Sample --> Normalize[Apply calibration]
  Normalize --> Quality[Attach quality flags]
  Quality --> PlantState[Classify plant state]
  PlantState --> Light[Update status light]
  Quality --> Envelope[Build telemetry envelope]
  Envelope --> Publish[Publish or queue]
  Publish --> Sleep[Wait for next interval]

Loading

The public reference focuses on the durable boundaries around that loop. For a fuller diagram set, see Visual Guide.

What This Repo Shows

• How a plant-sensing device can separate hardware adapters from product logic.
• How raw sensor readings become calibrated, typed telemetry.
• How local LED behavior can communicate device and plant state without requiring a screen.
• How cloud ingestion can be modeled without publishing private infrastructure.
• How to document an IoT product as a maintainable system instead of a single sketch.

Core Concepts

Concept	Public artifact
Sensor abstraction	reference-firmware/src/sensors/
Calibration lifecycle	docs/calibration.md
Telemetry contract	schemas/telemetry.schema.json
Device configuration	schemas/device-config.schema.json
Local status feedback	docs/led-status-system.md
Cloud data flow	docs/cloud-data-flow.md
Visual walkthrough	docs/visual-guide.md
Design tradeoffs	docs/design-decisions.md
Terms and vocabulary	docs/glossary.md

Repository Map

nomyk-device-core/
  docs/                 Architecture notes and design rationale
  diagrams/             Mermaid diagrams for system and state flows
  examples/             Safe example payloads for schemas and docs
  schemas/              Public JSON Schemas for telemetry and device config
  reference-firmware/   Small C++ reference implementation

Public Scope

This repo intentionally contains generic reference material only. It does not include:

• production API URLs, credentials, certificates, or auth flows
• private cloud infrastructure configuration
• real user, plant, or device data
• proprietary dashboard code
• exact commercial firmware
• manufacturing files or commercial BOM details

Start Here

1. Read Architecture for the system shape.
2. Review Telemetry Model and Calibration for the data pipeline.
3. Scan Visual Guide for the main diagrams.
4. Read Design Decisions for the tradeoffs behind the public reference.
5. Inspect examples/ for safe payloads that match the public schemas.
6. Browse reference-firmware for a dependency-free C++ sketch of the device loop.

Reference Firmware

The reference-firmware directory is not production firmware. It is deliberately small, portable C++ that demonstrates:

• sensor interfaces
• calibration profiles
• telemetry envelope construction
• status-light state selection
• a simple read-calibrate-publish loop

The code is meant to be readable and adaptable to Arduino, ESP-IDF, Zephyr, or another embedded environment.

Checks

GitHub Actions validates the public reference by checking JSON syntax, validating example payloads against the public schemas, scanning for common sensitive markers, building the C++ reference firmware, and running the reference tests.

To validate the public schemas and examples locally:

python -m pip install -r requirements-dev.txt
python scripts/validate_examples.py

If you have CMake and a C++17 compiler locally:

cd reference-firmware
cmake -S . -B build
cmake --build build
ctest --test-dir build --output-on-failure

License

MIT. See LICENSE.