Metadata-Version: 2.4
Name: jetstan_ev_software
Version: 0.1.9
Summary: The vehicle software payload for Jetstan electric vehicles - independently versioned from jetstan-agent (OTA delivery) and jetstan-cli (deploy tool).
Keywords: ev,vehicle-software,ota,automotive,raspberry-pi
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: python-dotenv==1.2.2
Requires-Dist: fastapi==0.140.7
Requires-Dist: uvicorn==0.51.0
Requires-Dist: numpy==2.5.1
Requires-Dist: onnxruntime==1.28.0
Provides-Extra: arduino
Requires-Dist: pyserial==3.5; extra == "arduino"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
Requires-Dist: httpx>=0.28.0; extra == "dev"

# jetstan_ev_software

The vehicle software payload for Jetstan electric vehicles — the code
that actually runs on the vehicle's Raspberry Pi and defines its
behavior. Published independently of `jetstan-agent` (the OTA delivery
mechanism) and `jetstan-cli` (the engineer-facing deploy tool): this
package is versioned, released, and deployed on its own schedule,
never tied to either.

```
jetstan-agent        = OTA/runtime agent (MQTT, self-update, process supervision)
jetstan-cli          = engineer-facing deployment CLI
jetstan_ev_software   = this package - what the vehicle actually runs
```

Import name: `software`. Distribution name on PyPI: `jetstan_ev_software`.

## What's inside

- **Arduino firmware + OTA flashing** (`software.arduino_updates`) —
  compiles the shipped motor-controller sketch with `arduino-cli`,
  flashes it over USB serial with `avrdude`, and verifies the board's
  contents against what was just written before trusting it.
- **Sensors & telemetry** (`software.sensors`) — reads live pack
  voltage/temperature back from the Arduino, and forwards motor speed
  commands to it over the same serial connection.
- **State-of-charge prediction** (`software.soc`) — an ONNX-exported
  model + FastAPI service for estimating battery state of charge from
  telemetry.
- **Deployment DAG** (`software.deployment`) — the task graph that
  compiles, flashes, and starts telemetry in the correct order every
  time the vehicle software activates, with real skip logic (not a
  blind cache) so nothing gets reflashed unnecessarily.
- **MQTT command extension point** (`software.handlers`) — this
  package's own custom MQTT commands, merged automatically into
  `jetstan-agent`'s router without `jetstan-agent` ever needing to know
  this package exists.

## How it gets onto a vehicle

```
jetstan deploy --release X --batch <batch>
    -> cloud-logics validates jetstan_ev_software==X on PyPI
    -> MQTT: {"type": "software.available", "version": "X"}
    -> jetstan-agent on the Pi -> software.handlers
    -> pip install --upgrade jetstan_ev_software==X
    -> restart -> deployment DAG compiles, flashes, and verifies
```

Not installed by hand in production — see `jetstan-agent`'s own
`jetstan-agent-install` for how a fresh Pi gets this package onto it in
the first place.

## Local development

```bash
cd software
pip install -e ".[dev]"
pytest
```

`ARDUINO_ENABLED=false` by default — Arduino compile/flash/telemetry
are opt-in via environment variable (see `.env.example`), so running
the test suite or importing this package never requires real hardware
to be attached.
