Initial definition of memory layout.

Author: kaklik

.github/workflows/generate.yml

@@ -0,0 +1,44 @@
+name: Generate device headers
+
+on:
+  push:
+    branches: ["main", "master"]
+    paths:
+      - "eeprom_layout.yaml"
+      - "xDOS_devices.yaml"
+      - "scripts/generate.py"
+  workflow_dispatch:
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Fetch the full branch so we can push back
+          ref: ${{ github.head_ref || github.ref_name }}
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: pip install -r scripts/requirements.txt
+
+      - name: Generate C/C++ and Python sources
+        run: python scripts/generate.py
+
+      - name: Commit generated files
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add generated/
+          if git diff --cached --quiet; then
+            echo "No changes to generated files."
+          else
+            git commit -m "chore: regenerate device headers from YAML [skip ci]"
+            git push
+          fi

.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.pyc
+*.pyo

eeprom_layout.yaml

@@ -0,0 +1,88 @@
+eeprom_layout:
+  name: dosimeter_eeprom
+  language: en
+  endianness: little
+  checksum:
+    algorithm: crc32
+    coverage: full_structure
+    checksum_field_behavior: replace_checksum_bytes_with_zero_before_crc
+
+  notes:
+    - "The EEPROM layout should be represented by a fixed C/C++ struct with explicit field sizes."
+    - "The same binary layout should be readable and writable from both Arduino/C++ and Python."
+    - "RTC validity should be determined from RTC chip status flags."
+    - "The last RTC reset/init time should be stored so the log header can contain an approximate device power-on estimate."
+    - "Device variants are intentionally ignored here; this is a single unified structure."
+    - "RTC history should be stored as an array of triplets, not as three separate arrays."
+
+  fields:
+    format_version:
+      type: uint16
+      description: EEPROM format version for backward compatibility
+
+    device_type:
+      type: uint16
+      description: Device type identifier
+      encoding: enum
+
+    crc32:
+      type: uint32
+      description: Structure checksum
+      crc_zero_fill: true
+
+    hardware_version:
+      type: struct
+      description: Device version and hardware revision
+      fields:
+        device_version:
+          type: uint8
+          range: "1-99"
+        hardware_revision:
+          type: uint8
+          range: "A-Z"
+
+    device_identifier:
+      type: char[24]
+      description: Human-readable device identifier
+      example: "animal name printed on enclosure"
+
+    operating_modes:
+      type: uint16
+      description: Operating modes and configuration flags
+
+    rtc_flags:
+      type: uint8
+      description: RTC capability and status flags
+      bit_mapping:
+        bit_0: has_rtc
+        bit_1: has_rtc_backup_battery
+        bit_2: rtc_initialized
+        bit_3: rtc_power_loss_detected
+        bit_4: geiger_mode_enabled
+        bit_5: led_enabled
+        bit_6: reserved
+        bit_7: reserved
+
+    rtc_history:
+      type: array
+      length: 5
+      description: History table of RTC-related reference points
+      item_type: struct
+      item_fields:
+        rtc_initialization_timestamp:
+          type: uint32
+          description: Time when RTC was reset or initialized
+        reference_timestamp:
+          type: uint32
+          description: Periodically updated reference time
+        rtc_value_at_reference_timestamp:
+          type: uint32
+          description: RTC counter/state captured when the reference timestamp was written
+
+    calibration_constants:
+      type: float[3]
+      description: Calibration parameters
+
+    calibration_version:
+      type: uint32
+      description: Calibration timestamp or calibration version

generated/__init__.py

@@ -0,0 +1,3 @@
+# Auto-generated — do not edit manually.
+from .xdos_devices import DeviceType, KnownDevice, KNOWN_DEVICES, KNOWN_DEVICES_BY_NAME
+from .eeprom_layout import DosimeterEeprom, RtcFlagsFlags

generated/eeprom_layout.h

@@ -0,0 +1,31 @@
+/* Auto-generated from eeprom_layout.yaml — do not edit manually. */
+#pragma once
+#include "xdos_devices.h"
+
+typedef struct __attribute__((packed)) {
+    uint16_t format_version;
+    uint16_t device_type;
+    uint32_t crc32;
+    struct __attribute__((packed)) {
+        uint8_t device_version;
+        uint8_t hardware_revision;
+    } hardware_version;
+    char device_identifier[24];
+    uint16_t operating_modes;
+    uint8_t rtc_flags;
+    struct __attribute__((packed)) {
+        uint32_t rtc_initialization_timestamp;
+        uint32_t reference_timestamp;
+        uint32_t rtc_value_at_reference_timestamp;
+    } rtc_history[5];
+    float calibration_constants[3];
+    uint32_t calibration_version;
+} DosimeterEeprom;
+
+/* Bit flags for field 'rtc_flags' */
+#define EEPROM_HAS_RTC (1u << 0)
+#define EEPROM_HAS_RTC_BACKUP_BATTERY (1u << 1)
+#define EEPROM_RTC_INITIALIZED (1u << 2)
+#define EEPROM_RTC_POWER_LOSS_DETECTED (1u << 3)
+#define EEPROM_GEIGER_MODE_ENABLED (1u << 4)
+#define EEPROM_LED_ENABLED (1u << 5)

generated/eeprom_layout.py

@@ -0,0 +1,42 @@
+# Auto-generated from eeprom_layout.yaml — do not edit manually.
+import ctypes
+import enum
+from .xdos_devices import DeviceType  # noqa: F401
+
+class RtcFlagsFlags(enum.IntFlag):
+    HAS_RTC = 1 << 0
+    HAS_RTC_BACKUP_BATTERY = 1 << 1
+    RTC_INITIALIZED = 1 << 2
+    RTC_POWER_LOSS_DETECTED = 1 << 3
+    GEIGER_MODE_ENABLED = 1 << 4
+    LED_ENABLED = 1 << 5
+
+class HardwareVersion(ctypes.LittleEndianStructure):
+    _pack_ = 1
+    _fields_ = [
+        ("device_version", ctypes.c_uint8),
+        ("hardware_revision", ctypes.c_uint8),
+    ]
+
+class RtcHistoryEntry(ctypes.LittleEndianStructure):
+    _pack_ = 1
+    _fields_ = [
+        ("rtc_initialization_timestamp", ctypes.c_uint32),
+        ("reference_timestamp", ctypes.c_uint32),
+        ("rtc_value_at_reference_timestamp", ctypes.c_uint32),
+    ]
+
+class DosimeterEeprom(ctypes.LittleEndianStructure):
+    _pack_ = 1
+    _fields_ = [
+        ("format_version", ctypes.c_uint16),
+        ("device_type", ctypes.c_uint16),
+        ("crc32", ctypes.c_uint32),
+        ("hardware_version", HardwareVersion),
+        ("device_identifier", ctypes.c_char * 24),
+        ("operating_modes", ctypes.c_uint16),
+        ("rtc_flags", ctypes.c_uint8),
+        ("rtc_history", RtcHistoryEntry * 5),
+        ("calibration_constants", ctypes.c_float * 3),
+        ("calibration_version", ctypes.c_uint32),
+    ]

generated/xdos_devices.h

@@ -0,0 +1,37 @@
+/* Auto-generated from xDOS_devices.yaml — do not edit manually. */
+#pragma once
+#include <stdint.h>
+
+typedef enum {
+    DEVICE_TYPE_UNKNOWN = 0,
+    DEVICE_TYPE_AIRDOS = 1,
+    DEVICE_TYPE_GEODOS = 2,
+    DEVICE_TYPE_LABDOS = 3,
+    DEVICE_TYPE_SPACEDOS = 4,
+} DeviceType;
+
+typedef struct {
+    const char *full_name;
+    DeviceType device_type;
+    uint8_t device_version;
+    char hardware_revision;  /* '\0' = no revision letter */
+} KnownDevice;
+
+static const KnownDevice KNOWN_DEVICES[] = {
+    {"AIRDOS01", DEVICE_TYPE_AIRDOS, 1, '\0'},
+    {"AIRDOS02", DEVICE_TYPE_AIRDOS, 2, '\0'},
+    {"AIRDOS03A", DEVICE_TYPE_AIRDOS, 3, 'A'},
+    {"AIRDOS03B", DEVICE_TYPE_AIRDOS, 3, 'B'},
+    {"AIRDOS04A", DEVICE_TYPE_AIRDOS, 4, 'A'},
+    {"AIRDOS04B", DEVICE_TYPE_AIRDOS, 4, 'B'},
+    {"AIRDOS04C", DEVICE_TYPE_AIRDOS, 4, 'C'},
+    {"GEODOS01", DEVICE_TYPE_GEODOS, 1, '\0'},
+    {"GEODOS02", DEVICE_TYPE_GEODOS, 2, '\0'},
+    {"LABDOS01", DEVICE_TYPE_LABDOS, 1, '\0'},
+    {"SPACEDOS01B", DEVICE_TYPE_SPACEDOS, 1, 'B'},
+    {"SPACEDOS02", DEVICE_TYPE_SPACEDOS, 2, '\0'},
+    {"SPACEDOS04", DEVICE_TYPE_SPACEDOS, 4, '\0'},
+};
+
+static const int KNOWN_DEVICE_COUNT =
+    (int)(sizeof(KNOWN_DEVICES) / sizeof(KNOWN_DEVICES[0]));

generated/xdos_devices.py

@@ -0,0 +1,39 @@
+# Auto-generated from xDOS_devices.yaml — do not edit manually.
+from __future__ import annotations
+import enum
+from dataclasses import dataclass
+from typing import Optional
+
+class DeviceType(enum.IntEnum):
+    UNKNOWN = 0
+    AIRDOS = 1
+    GEODOS = 2
+    LABDOS = 3
+    SPACEDOS = 4
+
+@dataclass(frozen=True)
+class KnownDevice:
+    full_name: str
+    device_type: DeviceType
+    device_version: int
+    hardware_revision: Optional[str]
+
+KNOWN_DEVICES: list[KnownDevice] = [
+    KnownDevice("AIRDOS01", DeviceType.AIRDOS, 1, None),
+    KnownDevice("AIRDOS02", DeviceType.AIRDOS, 2, None),
+    KnownDevice("AIRDOS03A", DeviceType.AIRDOS, 3, "A"),
+    KnownDevice("AIRDOS03B", DeviceType.AIRDOS, 3, "B"),
+    KnownDevice("AIRDOS04A", DeviceType.AIRDOS, 4, "A"),
+    KnownDevice("AIRDOS04B", DeviceType.AIRDOS, 4, "B"),
+    KnownDevice("AIRDOS04C", DeviceType.AIRDOS, 4, "C"),
+    KnownDevice("GEODOS01", DeviceType.GEODOS, 1, None),
+    KnownDevice("GEODOS02", DeviceType.GEODOS, 2, None),
+    KnownDevice("LABDOS01", DeviceType.LABDOS, 1, None),
+    KnownDevice("SPACEDOS01B", DeviceType.SPACEDOS, 1, "B"),
+    KnownDevice("SPACEDOS02", DeviceType.SPACEDOS, 2, None),
+    KnownDevice("SPACEDOS04", DeviceType.SPACEDOS, 4, None),
+]
+
+KNOWN_DEVICES_BY_NAME: dict[str, KnownDevice] = {
+    d.full_name: d for d in KNOWN_DEVICES
+}