usb-adc-mcp2221

Integracja z OqlOS

Zalecany układ

Proces usb-adc-mcp2221-api jest lokalnym adapterem sprzętowym. OqlOS odpytuje go po HTTP, zamiast importować backend HID wewnątrz głównego procesu. Dzięki temu ponowne otwarcie HID, uprawnienia udev i awaria biblioteki sprzętowej są izolowane.

Na BoardNet MCP2221A jest składnikiem wspólnej usługi usb-adc-stack-api :8214, która mapuje jego G1 jako ai01, a DFR1184 UART jako ai02 i ai03. Samodzielne API :8212 pozostaje narzędziem diagnostycznym, ale nie powinno działać równolegle ze stackiem, ponieważ oba procesy próbowałyby otworzyć ten sam interfejs HID.

Adafruit 4471 ── USB HID ── usb-adc-mcp2221-api :8212 ── HTTP ── OqlOS
                 └─ USB CDC /dev/ttyACM* (UART, niezależnie)

Kontrakt HTTP

Metoda i ścieżka	Znaczenie
`GET /health`	wykryte urządzenia USB i stan adaptera
`GET /api/v1/device`	możliwości sprzętu i identyfikacja
`GET /api/v1/adc`	odczyt G1–G3
`GET /api/v1/adc/{1..3}`	odczyt pojedynczego kanału
`GET /api/v1/i2c/scan`	adresy wykryte na magistrali I2C

Proponowane mapowanie kanałów OqlOS:

device: mcp2221a-adafruit-4471
transport: http
base_url: http://127.0.0.1:8212
channels:
  ai01: {endpoint: /api/v1/adc/1, pin: G1, unit: V}
  ai02: {endpoint: /api/v1/adc/2, pin: G2, unit: V}
  ai03: {endpoint: /api/v1/adc/3, pin: G3, unit: V}

Nie należy mapować tych kanałów jako rejestrów Modbus. Są to lokalne wejścia MCP2221A i mają odmienną rozdzielczość, zakres oraz model błędów.

Jednostka systemd

Przykładowa jednostka po instalacji pakietu w wirtualnym środowisku:

[Unit]
Description=OqlOS MCP2221A USB adapter
After=network.target

[Service]
Type=simple
User=oqlos
Group=plugdev
WorkingDirectory=/home/oqlos/usb-adc-mcp2221
Environment=MCP2221_REFERENCE_VOLTAGE=3.3
ExecStart=/home/oqlos/usb-adc-mcp2221/.venv/bin/usb-adc-mcp2221-api
Restart=on-failure
RestartSec=2

[Install]
WantedBy=multi-user.target

Ścieżki i konto trzeba dopasować do rzeczywistego wdrożenia. API domyślnie wiąże się z localhostem; wystawienie go do sieci wymaga osobnej decyzji o autoryzacji i zaporze.

Semantyka błędów

422 — nieprawidłowy kanał lub parametr;
503 — HID/EasyMCP2221 niedostępne albo błąd operacji sprzętowej;
/health zgłasza ok: false, jeśli VID/PID nie zostały wykryte.

Stan ok: true w /health potwierdza obecność USB i udaną komendę HID, ale nie potwierdza poprawności okablowania ani kalibracji sygnału na wejściu. Szczegóły backendu opisuje EASYMCP2221_BACKEND.md.

This site is open source. Improve this page.