Odoo IoT Box emulation¶

An unmodified Odoo Point of Sale can use the device as its customer-facing display, with no changes on the Odoo side: the device emulates the HTTP surface of a real Odoo IoT Box closely enough that pointing your POS's IoT/proxy address at it "just works" for the customer display, while behaving exactly like a real box with no other hardware attached for everything else (so it's safe to point a production POS at the device — nothing else the box would normally do gets broken or spoofed).

Both currently supported Odoo lines are covered: 17.0 and 18.x — their customer-display protocols are quite different under the hood, but this emulation handles both simultaneously, with no version switch to configure.

Enable the emulation¶

Disabled by default. Enable it via configuration:

curl -X PATCH http://10.99.0.1/api/v1/config \
  -H 'Content-Type: application/json' \
  -d '{"odoo": {"enabled": true, "http_port": 8069}}'

This is reboot_required — the emulation runs as a separate process started at boot, so reboot the device (POST /api/v1/device/reboot) after enabling it. http_port defaults to 8069, matching a real IoT Box; only change it if 8069 conflicts with something else on your network.

Web UI: Config page → odoo block (no dedicated page yet — set the fields directly).

Point the POS at the device¶

In Odoo's Point of Sale settings, set the IoT Box (or "proxy") address to the device's fixed USB address:

http://10.99.0.1:8069

Once the POS can reach that address, it will detect one device: a Display — this is the only "hardware" the emulation exposes; every other IoT feature (printers, scales, payment terminals, barcode readers) answers exactly as an empty, hardware-less box would, so those parts of the POS UI stay functional (showing "no device") without erroring out.

The device must be reachable from the browser running the POS web client — that's normally the same host machine the Pi is plugged into over USB (the POS calls the box directly from the browser). See the host setup guides (Windows, Linux) for getting the host's browser to reach 10.99.0.1.

Using the customer display in the POS¶

Once the POS is pointed at the device and detects the Display device, enabling "customer display" in the POS session behaves natively — no extra configuration on the mcd side:

Odoo 17.0: the POS pushes rendered HTML to the box, which the device shows via its embedded display page. Ownership handoff (if a second POS session takes control) behaves like a real box.
Odoo 18.x: the POS instead tells the box to navigate its browser to a page served by the Odoo server itself; the device just performs that navigation (display/navigate under the hood) — the actual display content is then rendered by the Odoo server, not by the device. This means the device must be able to reach your Odoo server over the network while a POS session is open (not just the USB link to the host) — see Configuration → Proxy if the device only has USB connectivity and needs to share the host's network access via a proxy.

Both versions' "close"/"refresh" actions and rotate-screen (18.x kiosk mode) map to the normal display and configuration API underneath, so the emulation stays in sync with whatever else you're doing to the device through the mcd API directly at the same time.

Limitations¶

HTTP only. A POS served over HTTPS cannot call the emulation's plain-HTTP port from the browser (mixed-content restrictions) — a real IoT Box normally fronts its own HTTPS port with its own certificate for this reason. The device's own API can serve HTTPS (uploading a certificate — see the API overview) but the Odoo emulation surface does not yet reuse it; keep the POS's own connection to Odoo on a scheme that lets it also reach the device over plain HTTP, or serve the POS itself over HTTP during evaluation.
No box registration or remote pairing. The device never registers itself with the Odoo server (/iot/setup), never opens the box's outbound WebSocket bus, and doesn't support the iot-proxy.odoo.com pairing-code flow. This only matters for POS features that require the box to show up as a registered iot.box record on the server; everything addressed by IP (which includes the customer display) is unaffected.
Display-only hardware. Printers, scales, barcode readers and payment terminals are not emulated beyond "not present" — if your POS setup needs any of those, they need to come from somewhere else; this feature covers the customer-facing screen only.
17.0 vs 18.x support window. Odoo versions before 17.0 (which used the older, now-removed hw_proxy addon) are not covered.

Troubleshooting¶

Symptom	Likely cause	Fix
POS never detects an IoT Box at the configured address	`odoo.enabled` is still `false`, or the device hasn't rebooted since enabling it	`GET /config`, confirm `odoo.enabled: true`, reboot if you just changed it
POS detects the box but shows no display device	Wrong port, or something else already listening on `8069`/`8082` on the device	Confirm `odoo.http_port`, check for port conflicts in configuration
18.x customer display shows "not connected" / 503	`displayd` itself is unreachable (e.g. mid-reboot, browser not yet up) — the emulation maps this straight to the real box's "No display connected" failure	Wait for the device to finish booting; check `GET /device/health`
18.x customer display never loads content	The device can't reach your Odoo server's origin over the network while showing the server-rendered page	Set up host connection sharing or `proxy.url` (see Configuration → Proxy)
Browser blocks the request entirely	POS served over HTTPS calling the device's plain-HTTP emulation port	See "Limitations" above — HTTPS is not yet supported for this feature