Odoo-Modules/fusion_iot/CLAUDE.md

# Fusion IoT — Claude Code Instructions

## Purpose

Fusion IoT lets Fusion Apps products ingest live sensor readings from
hardware mounted on a shop floor — initially tank temperature probes
for Fusion Plating, with room to grow into label printers, scales,
and any other device Odoo's IoT framework supports.

## Folder contents

```
fusion_iot/
├── iot_base/                # Repackaged from Odoo S.A. — shared JS utils
├── iot/                     # Repackaged from Odoo S.A. — IoT Box mgmt models + UI
├── fusion_plating_iot/      # Our wrapper — sensor→tank mapping + out-of-spec holds
├── pi/                      # Pi-side: lightweight systemd poller (no iot_drivers)
│   ├── fp_iot_poller.py
│   └── fp-iot-poller.service
└── scripts/                 # One-shot setup + smoke tests
```

## Live deployments

### Pi #1 — pilot probe (DS18B20, Tank TK-EN-01)

| Attribute | Value |
|-----------|-------|
| Hostname | `fp-iot-01` |
| LAN IP | `192.168.10.112` |
| **Tailscale IP** | **`100.108.41.97`** |
| SSH | `ssh fp-iot-01` (aliased in `~/.ssh/config`, key-based via Tailscale — no password, no sshpass) |
| User | `fp` |
| Probe serial | `28-000000b276e4` (DS18B20) |
| Poller service | `fp-iot-poller.service` — posts to entech every 30s |
| Poller config | `/etc/fp-iot/poller.conf` |
| Poller logs | `journalctl -u fp-iot-poller -f` |

**Tailscale auth**: pre-authed to the `gurpreet6672@` tailnet. Survives reboots (`tailscaled` enabled).

### entech LXC (Odoo server, hosted on our Proxmox — client's ERP runs here)

- `iot_base` + `iot` + `fusion_plating_iot` all installed
- Ingest endpoint (public): `POST https://erp.enplating.ca/fp/iot/ingest`
- Token lives in `ir.config_parameter['fusion_plating_iot.ingest_token']` — rotated via `scripts/fp_iot_setup_live_sensor.py` at setup time; rotate again in Settings → Technical → System Parameters as needed

**Why the public URL (not the LAN IP)**: the Pi needs to work at any
customer site, not just our office. Using the same URL the customer
types into a browser means zero reconfig when the Pi physically
moves between sites. `10.200.1.26:8069` would only work when the Pi
is on our internal network.

**Tailscale on entech**: attempted in LXC 111 but the unprivileged
container can't create a tun device and iptables isn't installable
(apt state is broken from an unrelated python3-lxml-html-clean conflict).
Userspace-networking mode also failed to start cleanly. Skipped — the
public HTTPS URL is strictly simpler anyway. If future ops need
internal Tailscale reach on entech, either (a) switch to a privileged
LXC with tun support, (b) run tailscaled on the host pve-worker5 and
reverse-proxy, or (c) fix the apt state first.

## Repackaging notes — `iot_base` + `iot`

Both copied as-is from `/Users/gurpreet/Github/RePackaged-Odoo/_dependencies/`
(tag Odoo 19). Both are already LGPL-3 upstream — no license flip needed.

**Gutted phone-home**:

| File | Change |
|------|--------|
| `iot/models/update.py` | `Publisher_WarrantyContract._get_message` override REMOVED (no more IoT-Box counting-back to Odoo S.A. for enterprise licensing) |
| `iot/iot_handlers/lib/load_worldline_library.sh` | DELETED (proprietary Worldline payment lib fetch from download.odoo.com — we don't use Worldline) |

**Left intact** (NOT phone-home, don't remove):

- `ir_config_parameter.py` — broadcasts `web.base.url` changes to paired IoT boxes via the internal IoT channel (not the internet)
- `iot_box.py.version_commit_url` — cosmetic link to odoo/odoo on GitHub
- `controllers/main.py` — serves the iot handlers zip to the Pi (this is the point of the module)

## `fusion_plating_iot` — the wrapper

### Models

**`fp.tank.sensor`** — maps a physical sensor to a tank + parameter
- `device_serial` — hardware unique ID (e.g. DS18B20 1-Wire address)
- `iot_device_id` — optional link to `iot.device` if the sensor comes in via Pi proxy
- `tank_id` / `bath_id` — where the sensor lives
- `parameter_id` — what bath parameter it reports (temperature, pH, etc.)
- `alert_min_override` / `alert_max_override` — per-sensor spec override; else inherits from `fusion.plating.bath.parameter.target_min/max`
- Cached `last_reading_value` / `last_reading_at` / `last_reading_in_spec` for fast list views

**`fp.tank.reading`** — time-series log of every reading
- Append-only — never updated/deleted. The compliance record of bath history.
- `create()` evaluates each reading against the sensor's alert range
- Raises a `fusion.plating.quality.hold` ONCE on the transition from in-spec → out-of-spec (no spam)

**`fusion.plating.tank`** — extended with `x_fc_sensor_ids` o2m + `x_fc_has_out_of_spec` bool for the tank form.

### Endpoint — `POST /fp/iot/ingest`

For sensors that skip the Pi proxy and POST directly over HTTP.

- Auth: `X-FP-IOT-Token` header OR `"token"` key in JSON body, compared to `ir.config_parameter[fusion_plating_iot.ingest_token]` using `hmac.compare_digest`
- Seeded token value: `CHANGE-ME-AFTER-INSTALL` — **MUST be rotated immediately after install** via Settings → Technical → System Parameters
- Payload: single `{device_serial, value, read_at}` OR batch `{readings: [...]}`
- Response: 200 + `{ok: true, accepted: N}`, 401 on auth fail, 404 if device_serial unknown

### Dependencies

- `iot` — the server-side Odoo IoT module (in this same folder, needs to be installed first)
- `fusion_plating` — for `fusion.plating.tank` + `fusion.plating.bath.parameter`
- `fusion_plating_quality` — for `fusion.plating.quality.hold`

### Not yet — Phase B (when Pi hardware arrives)

- DS18B20 handler module for `iot_drivers` (the Pi-side proxy)
- Systemd service config for running `iot_drivers` on vanilla Raspberry Pi OS
- Pi firmware README

## Deployment to entech (LXC 111)

```bash
# 1. Sync all three modules
rsync -av fusion_iot/iot_base/        pve-worker5:/tmp/iot_base/
rsync -av fusion_iot/iot/             pve-worker5:/tmp/iot/
rsync -av fusion_iot/fusion_plating_iot/ pve-worker5:/tmp/fpi/

ssh pve-worker5 "pct exec 111 -- bash -c '
  mv /tmp/iot_base /mnt/extra-addons/custom/
  mv /tmp/iot /mnt/extra-addons/custom/
  mv /tmp/fpi /mnt/extra-addons/custom/fusion_plating_iot
  chown -R odoo:odoo /mnt/extra-addons/custom/iot_base /mnt/extra-addons/custom/iot /mnt/extra-addons/custom/fusion_plating_iot
'"

# 2. Install modules (order matters)
ssh pve-worker5 "pct exec 111 -- su - odoo -s /bin/bash -c \
  \"/usr/bin/odoo -c /etc/odoo/odoo.conf -d admin -i iot_base,iot,fusion_plating_iot --stop-after-init\""

# 3. Verify
#   - Settings → Technical → IoT menu appears
#   - Plating → Operations → Sensors & Readings menu appears
#   - curl test against /fp/iot/ingest (see README)
```

## Test commands

```bash
# Set a known token
odoo shell> env['ir.config_parameter'].set_param('fusion_plating_iot.ingest_token', 'test-secret-123')

# Create a sensor manually
odoo shell> env['fp.tank.sensor'].create({
    'name': 'Test probe',
    'device_serial': '28-test000001',
    'device_kind': 'ds18b20',
    'tank_id': <some_tank.id>,
    'parameter_id': <temperature_param.id>,
})

# POST a reading
curl -X POST http://entech:8069/fp/iot/ingest \
  -H 'Content-Type: application/json' \
  -H 'X-FP-IOT-Token: test-secret-123' \
  -d '{"device_serial":"28-test000001","value":87.3}'
# → {"ok":true,"accepted":1}

# Simulate out-of-spec reading (assuming target_max=90)
curl -X POST http://entech:8069/fp/iot/ingest \
  -H 'Content-Type: application/json' \
  -H 'X-FP-IOT-Token: test-secret-123' \
  -d '{"device_serial":"28-test000001","value":95.0}'
# → reading created + fusion.plating.quality.hold auto-raised
```