@@ -0,0 +1,32 @@
  + name: A-SW ALICE pipeline
  + 
  + on:
  +   push:
  +     branches: [main, "feature/**"]
  +   pull_request:
  + 
  + jobs:
  +   contracts:
  +     runs-on: ubuntu-latest
  +     steps:
  +       - uses: actions/checkout@v4
  +       - name: Validate machine-readable contracts
  +         run: python -m json.tool contracts/telemetry.schema.json >/dev/null
  + 
  +   unit-test:
  +     runs-on: ubuntu-latest
  +     steps:
  +       - uses: actions/checkout@v4
  +       - name: Run ALICE state-machine tests
  +         run: python -m unittest discover -s tests -v
  + 
  +   package:
  +     runs-on: ubuntu-latest
  +     needs: [contracts, unit-test]
  +     steps:
  +       - uses: actions/checkout@v4
  +       - name: Build the teaching artifact
  +         run: |
  +           mkdir -p dist
  +           tar -czf dist/alice-sdv-reference.tar.gz edge contracts profiles routes README.md
  +           shasum -a 256 dist/alice-sdv-reference.tar.gz > dist/checksums.sha256

added .gitignore +3−0 View file

@@ -0,0 +1,3 @@

1 + __pycache__/

2 + *.pyc

3 + dist/

added README.md +25−0 View file

@@ -0,0 +1,25 @@
  + # ALICE SDV reference module
  + 
  + This repository is the first executable teaching fixture for the A-SW Hub
  + code-to-deployment pipeline. It models a small, hardware-independent slice of
  + the ALICE control stack so that a local runner can validate the same contracts
  + before a Jetson or MCU is connected.
  + 
  + ## Included vertical slice
  + 
  + - explicit `IDLE -> ENTER -> PATROL -> RETURN -> IDLE` state transitions
  + - `FAULT` entry and reset behavior
  + - machine-readable MQTT telemetry contract
  + - ALICE profile and sample route fixtures
  + - unit tests with no external runtime dependencies
  + - a Gitea Actions workflow ready for the local runner
  + 
  + ## Local test
  + 
  + ```bash
  + python -m unittest discover -s tests -v
  + python -m json.tool contracts/telemetry.schema.json >/dev/null
  + ```
  + 
  + The next increment adds the simulated MQTT broker, package manifest, artifact
  + checksums, and a local deployment target.

added contracts/telemetry.schema.json +15−0 View file

@@ -0,0 +1,15 @@
  + {
  +   "$schema": "https://json-schema.org/draft/2020-12/schema",
  +   "$id": "https://asw.local/contracts/alice/telemetry.schema.json",
  +   "title": "ALICE telemetry",
  +   "type": "object",
  +   "additionalProperties": false,
  +   "required": ["device_id", "state", "battery", "fault", "timestamp"],
  +   "properties": {
  +     "device_id": { "type": "string", "pattern": "^[a-z0-9-]+$" },
  +     "state": { "enum": ["IDLE", "ENTER", "PATROL", "RETURN", "FAULT"] },
  +     "battery": { "type": "number", "minimum": 0, "maximum": 100 },
  +     "fault": { "type": ["string", "null"] },
  +     "timestamp": { "type": "string", "format": "date-time" }
  +   }
  + }

added edge/__init__.py +1−0 View file

@@ -0,0 +1 @@

1 + """Hardware-independent ALICE edge-domain examples."""

added edge/state_machine.py +51−0 View file

@@ -0,0 +1,51 @@
  + from __future__ import annotations
  + 
  + from dataclasses import dataclass
  + from enum import Enum
  + 
  + 
  + class State(str, Enum):
  +     IDLE = "IDLE"
  +     ENTER = "ENTER"
  +     PATROL = "PATROL"
  +     RETURN = "RETURN"
  +     FAULT = "FAULT"
  + 
  + 
  + class Event(str, Enum):
  +     START_PATROL = "START_PATROL"
  +     ENTERED_ROUTE = "ENTERED_ROUTE"
  +     PATROL_COMPLETED = "PATROL_COMPLETED"
  +     RETURNED_HOME = "RETURNED_HOME"
  +     ABORT = "ABORT"
  +     SAFETY_TIMEOUT = "SAFETY_TIMEOUT"
  +     RESET = "RESET"
  + 
  + 
  + TRANSITIONS: dict[tuple[State, Event], State] = {
  +     (State.IDLE, Event.START_PATROL): State.ENTER,
  +     (State.ENTER, Event.ENTERED_ROUTE): State.PATROL,
  +     (State.ENTER, Event.ABORT): State.RETURN,
  +     (State.PATROL, Event.PATROL_COMPLETED): State.RETURN,
  +     (State.PATROL, Event.ABORT): State.RETURN,
  +     (State.RETURN, Event.RETURNED_HOME): State.IDLE,
  +     (State.ENTER, Event.SAFETY_TIMEOUT): State.FAULT,
  +     (State.PATROL, Event.SAFETY_TIMEOUT): State.FAULT,
  +     (State.RETURN, Event.SAFETY_TIMEOUT): State.FAULT,
  +     (State.FAULT, Event.RESET): State.IDLE,
  + }
  + 
  + 
  + class InvalidTransition(ValueError):
  +     """Raised when an event is not allowed from the current state."""
  + 
  + 
  + @dataclass(frozen=True)
  + class PatrolStateMachine:
  +     state: State = State.IDLE
  + 
  +     def dispatch(self, event: Event) -> "PatrolStateMachine":
  +         next_state = TRANSITIONS.get((self.state, event))
  +         if next_state is None:
  +             raise InvalidTransition(f"{event} is not allowed from {self.state}")
  +         return PatrolStateMachine(next_state)

added profiles/alice.yaml +10−0 View file

@@ -0,0 +1,10 @@
  + device_id: alice-01
  + control:
  +   tick_seconds: 0.2
  +   watchdog_seconds: 0.5
  +   command_stream_hz: 50
  + safety:
  +   corridor_stop_m: 0.30
  +   corridor_resume_m: 0.45
  +   fault_after_seconds: 5
  + route: office-patrol-01

added routes/office-patrol-01.yaml +8−0 View file

@@ -0,0 +1,8 @@
  + id: office-patrol-01
  + frame: map
  + arrival_radius_m: 0.12
  + waypoints:
  +   - { x: 0.0, y: 0.0, heading: 0.0 }
  +   - { x: 2.0, y: 0.0, heading: 0.0 }
  +   - { x: 2.0, y: 1.5, heading: 1.57 }
  +   - { x: 0.0, y: 1.5, heading: 3.14 }

added tests/test_state_machine.py +32−0 View file

@@ -0,0 +1,32 @@
  + import unittest
  + 
  + from edge.state_machine import Event, InvalidTransition, PatrolStateMachine, State
  + 
  + 
  + class PatrolStateMachineTest(unittest.TestCase):
  +     def test_nominal_patrol_returns_to_idle(self) -> None:
  +         machine = PatrolStateMachine()
  +         for event in (
  +             Event.START_PATROL,
  +             Event.ENTERED_ROUTE,
  +             Event.PATROL_COMPLETED,
  +             Event.RETURNED_HOME,
  +         ):
  +             machine = machine.dispatch(event)
  +         self.assertEqual(machine.state, State.IDLE)
  + 
  +     def test_abort_during_enter_returns_home(self) -> None:
  +         machine = PatrolStateMachine().dispatch(Event.START_PATROL)
  +         self.assertEqual(machine.dispatch(Event.ABORT).state, State.RETURN)
  + 
  +     def test_safety_timeout_enters_fault(self) -> None:
  +         machine = PatrolStateMachine().dispatch(Event.START_PATROL).dispatch(Event.ENTERED_ROUTE)
  +         self.assertEqual(machine.dispatch(Event.SAFETY_TIMEOUT).state, State.FAULT)
  + 
  +     def test_invalid_transition_is_rejected(self) -> None:
  +         with self.assertRaises(InvalidTransition):
  +             PatrolStateMachine().dispatch(Event.RETURNED_HOME)
  + 
  + 
  + if __name__ == "__main__":
  +     unittest.main()