feat(ecs): slice 1 — I2C field model, board registers, pixel (ports of _fields/board/pixel.py)
ci / test (push) Canceled after 0s
ci / build-arm64 (push) Canceled after 0s

- innesco-ecs: declarative I2cField (byte/enum/bool/int) with the exact
  read-modify-write semantics of _fields.py, incl. the raw-byte getter quirk
- Board: mux, fastin_src, external_dac, sel_data_en_src, si_clk_oe,
  si_clk_in, analog_power, direction_register + config_crystal sequencer
- Pixel: power/frontend/adj/ctrl + finetune_dac nibble logic
- 7 integration tests against a fake data_server (register-file mock)
- faithful-port findings #7 (enum codes wider than mask don't round-trip
  in Python either) and #8 (crystal hi/lo aliasing) documented
- 21 tests green across the workspace
This commit is contained in:
BobBot
2026-11-12 23:19:23 +00:00
parent f4f08a0210
commit eff04cfa10
11 changed files with 963 additions and 22 deletions
Generated
+7
View File
@@ -14,6 +14,13 @@ dependencies = [
name = "innesco-decoding"
version = "0.1.0"
[[package]]
name = "innesco-ecs"
version = "0.1.0"
dependencies = [
"innesco-protocol",
]
[[package]]
name = "innesco-protocol"
version = "0.1.0"
+1
View File
@@ -3,6 +3,7 @@ resolver = "2"
members = [
"crates/innesco-protocol",
"crates/innesco-decoding",
"crates/innesco-ecs",
"crates/innesco-cli",
]
+2
View File
@@ -8,3 +8,5 @@
- Target: AMD Kria K26 (aarch64, quad Cortex-A53, Ubuntu 22.04).
- Build artifacts → /tmp/innesco-rs-target (NFS too slow for target/).
- 2026-11-12: initial port, golden tests green, pushed to Gitea main.
- 2026-11-12: arm64 musl build verified (static, AArch64); craft-anything-cli installed.
- 2026-11-12: slice 1 of OP3 (innesco-ecs: _fields/board/pixel) — 21 tests green; 2 faithful-port findings (enum non-round-trip, crystal hi/lo aliasing). Decisions: polars-rs + S3 crucial (OP1), CI deprioritized. Reminder cron 2026-11-18 09:00 for raw frames.
+23 -22
View File
@@ -50,35 +50,36 @@ skip-and-count instead of abort on malformed packets).
## Open Points
(user-editable — tell me here what to focus on; details agreed with Lucio 2026-11-12)
(details agreed with Lucio 2026-11-12; user-editable — tell me what to focus on)
1. **Storage layer** (after #3): `storage.py` is a 185-line `ParquetStorage`
thread (queue → parquet → S3/MinIO upload, prometheus counters).
Rust port options: **arrow-rs** (lighter; arrow is SoA-native, closes the
AoS/SoA divergence) vs **polars-rs** (feature parity with notebooks, heavy).
*Decisions needed*: (a) arrow-rs vs polars, (b) S3 in-process vs local-only,
(c) keep the exact Python column schema (notebook compatibility).
1. **Storage layer** (after #3) — *decisions taken*: **polars-rs** for parquet
I/O (feature parity with the notebooks) + **S3/MinIO upload is crucial**
(no local storage on the board — data must be pushed out). Schema need not
be byte-identical, but must keep the notebook query surface: columns
`address, ix, iy, quadrant, tot, adj_ctrl, period, integr_time, v_inj`
(grep of notebooks 02/04/05/06/07) and the file-path conventions
(`results/{date}/analog_power=*/dcos-*.parquet`, `dataset-tag-{n}.parquet`
— duckdb queries use `SELECT *`, so paths matter more than column order).
Original: 185-line `ParquetStorage` thread (queue → parquet → S3).
2. **REST API** (after #3): 7 endpoints in `rest_api.py` (`/ping`, `/metrics`,
`/state`, `PUT /chunksize`, `POST /tag`, `POST /daq`, `GET /dataset`).
Port: axum + tokio in a separate crate with feature flag (library stays
dependency-free). `/state` and `/daq` depend on #3; the other four can be
ported independently.
3. **Board/slow-control model** (biggest item): `ecs/` ≈ 2,358 lines
(asic_state 626, mattonella_state 569, quadrant 502, mattonella 426, …)
+ `Board.py` 268 + `DataProcessor.py` 425. Suggested slices:
(1) board+pixel 166 lines → (2) mattonella(+state) 995 → (3) asic_state 626
→ (4) quadrant 502 → (5) daq+DataProcessor 574. Mirror-1:1 first (golden
I2C tests comparable with Python), type-state validation later.
Depends only on the (already ported) protocol crate.
3. **Board/slow-control model** — **IN PROGRESS, slice 1 done**:
- ✅ slice 1: `_fields.py` (199 L) + `board.py` (89) + `pixel.py` (77) →
`crates/innesco-ecs` (7 integration tests against a fake data_server,
incl. RMW semantics and the crystal-config sequencer; two faithful-port
findings documented in docs/porting-notes.md #7/#8).
- next: (2) mattonella(+state) 995 L → (3) asic_state 626 → (4) quadrant 502
→ (5) daq+DataProcessor 574. Mirror-1:1 first, type-state validation later.
4. **Real-board validation**: no qemu here, no network to the boards.
(a) *A raw frame dump from a real acquisition* (even small) → decoder
validated on physical data as an official golden test — **highest value,
zero prerequisites**. (b) network access to a Kria running `data_server`
zero prerequisites. Lucio will try next week; reminder set for
Wed 2026-11-18 09:00.** (b) network access to a Kria running `data_server`
→ live `innesco-cli ping` + harmless I2C read (`0x7E`).
5. **CI runner**: verified 2026-11-12 — no Actions runs on this Gitea repo
and runner admin endpoint is not accessible → no runner configured.
Self-hosting one here is impossible (no Docker daemon). Options: register
a runner on a machine with Docker, or rely on local
`scripts/build-arm64.sh --run-tests` until then.
**Recommended order**: 4(a) → 3 → 1 → 2 → 5.
5. **CI runner** — *deprioritized (Lucio 2026-11-12)*: verified 2026-11-12
that no Actions runner exists on this Gitea and self-hosting is impossible
here (no Docker daemon). Local `scripts/build-arm64.sh --run-tests` is the
working CI substitute.
+11
View File
@@ -0,0 +1,11 @@
[package]
name = "innesco-ecs"
description = "Slow-control register model for IGNITE64 boards (Rust port of innesco/ecs: _fields.py, board.py, pixel.py)"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
[dependencies]
innesco-protocol = { path = "../innesco-protocol" }
+152
View File
@@ -0,0 +1,152 @@
//! Rust port of `innesco/ecs/board.py` — static registers of the carrier
//! board plus `config_crystal`.
use std::path::Path;
use innesco_protocol::{Connection, Request};
use crate::fields::{FieldAddress, I2cField};
/// Register model of the carrier board (all addresses are board-global, so
/// the fields here carry fixed addresses — no per-instance context needed).
pub struct Board;
const NONE: Option<FieldAddress> = None;
impl Board {
/// Board I2C multiplexer channel.
pub const MUX: I2cField = I2cField::enum_(
FieldAddress::Fixed(0x70),
NONE,
0x0F,
&[(0, "OFF"), (1, "SW"), (2, "NW"), (4, "SE"), (8, "NE")],
);
/// Ingress source for FastIN signals.
pub const FASTIN_SRC: I2cField = I2cField::enum_(
FieldAddress::Fixed(0x20),
Some(FieldAddress::Fixed(0x0A)),
0x01,
&[(0, "J12"), (0xFF, "LVDS")],
);
/// External DAC power state.
pub const EXTERNAL_DAC: I2cField = I2cField::enum_(
FieldAddress::Fixed(0x20),
Some(FieldAddress::Fixed(0x0A)),
0x02,
&[(0, "ON"), (0xFF, "OFF")],
);
/// Source data.
pub const SEL_DATA_EN_SRC: I2cField = I2cField::enum_(
FieldAddress::Fixed(0x20),
Some(FieldAddress::Fixed(0x0A)),
0x04,
&[(0, "KRIA"), (0xFF, "J14")],
);
/// SI_CLK output enable.
pub const SI_CLK_OE: I2cField = I2cField::enum_(
FieldAddress::Fixed(0x20),
Some(FieldAddress::Fixed(0x0A)),
0x08,
&[(0, "OFF"), (0xFF, "ON")],
);
/// SI_CLK input.
pub const SI_CLK_IN: I2cField = I2cField::enum_(
FieldAddress::Fixed(0x20),
Some(FieldAddress::Fixed(0x0A)),
0x30,
&[(0x00, "SMA"), (0x10, "KRIA"), (0x20, "NONE"), (0x30, "CRYSTAL")],
);
/// Analog power state (note the inverted encoding: 0x00 = ON, 0x40 = OFF).
pub const ANALOG_POWER: I2cField = I2cField::enum_(
FieldAddress::Fixed(0x20),
Some(FieldAddress::Fixed(0x0A)),
0x40,
&[(0x00, "ON"), (0x40, "OFF")],
);
/// PIN direction register ("PIN is configured as I/O").
pub const DIRECTION_REGISTER: I2cField =
I2cField::byte(FieldAddress::Fixed(0x20), Some(FieldAddress::Fixed(0x00)));
/// Port of `Board.config_crystal`: parse a CSV of `addr,value` hex pairs
/// and program the crystal controller at `0x75` (write high byte of the
/// register address to subaddress 0x01, then the value to subaddress
/// `addr & 0xFF`). Blank lines, comments (`#`) and malformed lines are
/// skipped (a warning goes to stderr, like the Python `logging.warning`).
///
/// Returns the number of `(addr, value)` pairs actually written.
pub fn config_crystal(
config_file: &Path,
conn: &mut Connection,
) -> Result<usize, CrystalError> {
let text = std::fs::read_to_string(config_file)
.map_err(|e| CrystalError::Io(config_file.display().to_string(), e))?;
let mut rows: Vec<(u8, u8, u8)> = Vec::new();
for line in text.lines() {
let trimmed = line.trim();
if trimmed.is_empty() || trimmed.starts_with('#') {
continue;
}
match Self::parse_crystal_line(trimmed) {
Some(row) => rows.push(row),
None => eprintln!("warning: skipping invalid line in crystal config: {trimmed}"),
}
}
conn.send(&Request::Ping { payload: b"Configuring crystal...".to_vec() })?;
for (hi, lo, value) in &rows {
conn.send(&Request::WriteSub {
address: 0x75,
subaddress: 0x01,
payload: vec![*hi],
})?;
conn.send(&Request::WriteSub {
address: 0x75,
subaddress: *lo,
payload: vec![*value],
})?;
}
conn.send(&Request::Ping { payload: b"Crystal configuration complete.".to_vec() })?;
Ok(rows.len())
}
/// Line format: `addr,value` — both hex, addr is 16-bit, value 8-bit.
/// (Python accepts decimal-looking tokens too because `int(x, 16)`; here
/// we accept hex with or without the `0x` prefix — same reader audience.)
fn parse_crystal_line(line: &str) -> Option<(u8, u8, u8)> {
let (addr_part, value_part) = line.split_once(',')?;
let addr = u16::from_str_radix(addr_part.trim().trim_start_matches("0x"), 16).ok()?;
let value = u8::from_str_radix(value_part.trim().trim_start_matches("0x"), 16).ok()?;
Some(((addr >> 8) as u8, (addr & 0xFF) as u8, value))
}
}
#[derive(Debug)]
pub enum CrystalError {
Io(String, std::io::Error),
Protocol(innesco_protocol::ProtocolError),
}
impl std::fmt::Display for CrystalError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
CrystalError::Io(path, e) => write!(f, "cannot read {path}: {e}"),
CrystalError::Protocol(e) => write!(f, "protocol error: {e}"),
}
}
}
impl std::error::Error for CrystalError {}
impl From<innesco_protocol::ProtocolError> for CrystalError {
fn from(e: innesco_protocol::ProtocolError) -> Self {
CrystalError::Protocol(e)
}
}
+307
View File
@@ -0,0 +1,307 @@
//! Rust port of `innesco/ecs/_fields.py`.
//!
//! Each I2C register field is a declarative [`I2cField`] describing
//! (address, subaddress, mask, bit shift, kind). Address/subaddress can be
//! fixed constants or resolved per instance (the Python `from_attribute`
//! closures, used by Pixel). Read-modify-write semantics mirror the Python
//! descriptors byte for byte, including the quirk that the `i2c_byte`
//! *getter* returns the full raw byte (mask NOT applied on read) while the
//! enum/int getters do apply it.
use innesco_protocol::{Connection, ProtocolError, Request, Response};
/// Where a field's I2C address (or subaddress) comes from.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FieldAddress {
Fixed(u8),
/// Python `from_attribute("_mattonella_id")`.
MattonellaId,
/// Python `from_attribute("_pixel_id")`.
PixelId,
}
/// Per-instance values used to resolve [`FieldAddress::MattonellaId`] /
/// [`FieldAddress::PixelId`].
#[derive(Debug, Clone, Copy, Default)]
pub struct FieldContext {
pub mattonella_id: u8,
pub pixel_id: u8,
}
/// Field kind (Python descriptor constructors).
#[derive(Debug, Clone, Copy)]
pub enum Kind {
/// `i2c_byte`: getter returns the RAW byte (no mask on read).
Byte,
/// `i2c_bool`: masked bit test on read, set/clear full mask on write.
Bool,
/// `i2c_int`: `(raw & mask) >> shift` on read.
Int,
/// `i2c_enum`: named values, hex-string fallback for unknown codes.
Enum(&'static [(u8, &'static str)]),
}
/// Declarative I2C register field (one Python descriptor).
#[derive(Debug, Clone, Copy)]
pub struct I2cField {
pub address: FieldAddress,
pub subaddress: Option<FieldAddress>,
/// Effective mask (for `i2c_int` this is `(mask << shift) & 0xFF`,
/// exactly like the Python constructor).
pub mask: u8,
pub shift: u8,
pub kind: Kind,
}
#[derive(Debug)]
pub enum FieldError {
Protocol(ProtocolError),
/// Server answered with a non-zero status (Python would have failed
/// more obscurely; we make it explicit).
Server { status: u8, message: String },
/// Response carried no I2C data where one byte was required.
EmptyPayload,
/// Value out of range / not a valid enum member (Python `ValueError`).
InvalidValue { value: String, reason: String },
}
impl std::fmt::Display for FieldError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
FieldError::Protocol(e) => write!(f, "protocol error: {e}"),
FieldError::Server { status, message } => {
write!(f, "server error {status}: {message}")
}
FieldError::EmptyPayload => write!(f, "empty I2C payload"),
FieldError::InvalidValue { value, reason } => {
write!(f, "invalid value {value}: {reason}")
}
}
}
}
impl std::error::Error for FieldError {}
impl From<ProtocolError> for FieldError {
fn from(e: ProtocolError) -> Self {
FieldError::Protocol(e)
}
}
impl I2cField {
/// `i2c_byte(...)` — full-byte field, optional validator kept out of v1
/// (no validator is used in board.py/pixel.py slice).
pub const fn byte(address: FieldAddress, subaddress: Option<FieldAddress>) -> Self {
I2cField { address, subaddress, mask: 0xFF, shift: 0, kind: Kind::Byte }
}
/// `i2c_enum(...)` — `values` maps codes to names.
pub const fn enum_(
address: FieldAddress,
subaddress: Option<FieldAddress>,
mask: u8,
values: &'static [(u8, &'static str)],
) -> Self {
I2cField { address, subaddress, mask, shift: 0, kind: Kind::Enum(values) }
}
/// `i2c_bool(...)` — mask is the single bit (or bits) to set/clear.
pub const fn bool_(
address: FieldAddress,
subaddress: Option<FieldAddress>,
mask: u8,
) -> Self {
I2cField { address, subaddress, mask, shift: 0, kind: Kind::Bool }
}
/// `i2c_int(...)` — the Python constructor applies
/// `mask = (mask << shift) & 0xFF` at definition time; same here.
pub const fn int(
address: FieldAddress,
subaddress: Option<FieldAddress>,
shift: u8,
mask: u8,
) -> Self {
I2cField {
address,
subaddress,
mask: ((mask as u16) << shift) as u8 & 0xFF,
shift,
kind: Kind::Int,
}
}
fn resolve(&self, which: FieldAddress, ctx: FieldContext) -> u8 {
match which {
FieldAddress::Fixed(a) => a,
FieldAddress::MattonellaId => ctx.mattonella_id,
FieldAddress::PixelId => ctx.pixel_id,
}
}
fn bus(&self, ctx: FieldContext) -> (u8, Option<u8>) {
(
self.resolve(self.address, ctx),
self.subaddress.map(|s| self.resolve(s, ctx)),
)
}
fn send(&self, conn: &mut Connection, request: &Request) -> Result<Response, FieldError> {
let resp = conn.send(request)?;
if resp.is_error() {
return Err(FieldError::Server {
status: resp.status,
message: resp.message(),
});
}
Ok(resp)
}
fn read_one(&self, conn: &mut Connection, ctx: FieldContext) -> Result<u8, FieldError> {
let (address, subaddress) = self.bus(ctx);
let request = match subaddress {
Some(sub) => Request::ReadSub { address, subaddress: sub, length: 1 },
None => Request::Read { address, length: 1 },
};
let resp = self.send(conn, &request)?;
resp.i2c_data()
.first()
.copied()
.ok_or(FieldError::EmptyPayload)
}
fn write_one(
&self,
conn: &mut Connection,
ctx: FieldContext,
payload: u8,
) -> Result<(), FieldError> {
let (address, subaddress) = self.bus(ctx);
let request = match subaddress {
Some(sub) => Request::WriteSub { address, subaddress: sub, payload: vec![payload] },
None => Request::Write { address, payload: vec![payload] },
};
self.send(conn, &request)?;
Ok(())
}
/// `unchanged` part of a read-modify-write: Python reads the remote byte
/// and keeps everything outside the mask — unless `mask == 0xFF`, where
/// it writes without reading at all.
fn unchanged_part(
&self,
conn: &mut Connection,
ctx: FieldContext,
) -> Result<u8, FieldError> {
if self.mask == 0xFF {
Ok(0x00)
} else {
Ok(self.read_one(conn, ctx)? & !self.mask)
}
}
// ------------------------------------------------------------------
// Readers
// ------------------------------------------------------------------
/// `i2c_byte` getter: the FULL raw byte (mask not applied — Python quirk,
/// preserved deliberately).
pub fn read_byte(&self, conn: &mut Connection, ctx: FieldContext) -> Result<u8, FieldError> {
self.read_one(conn, ctx)
}
/// `i2c_bool` getter: `(raw & mask) != 0`.
pub fn read_bool(&self, conn: &mut Connection, ctx: FieldContext) -> Result<bool, FieldError> {
Ok(self.read_one(conn, ctx)? & self.mask != 0)
}
/// `i2c_int` getter: `(raw & mask) >> shift`.
pub fn read_int(&self, conn: &mut Connection, ctx: FieldContext) -> Result<u8, FieldError> {
Ok((self.read_one(conn, ctx)? & self.mask) >> self.shift)
}
/// `i2c_enum` getter: masked code mapped to its name, hex fallback for
/// unknown codes (Python: `enum.get(ret, f"{ret:02X}")`).
pub fn read_enum(&self, conn: &mut Connection, ctx: FieldContext) -> Result<String, FieldError> {
let ret = self.read_one(conn, ctx)? & self.mask;
let Kind::Enum(values) = self.kind else {
return Err(FieldError::InvalidValue {
value: "read_enum".into(),
reason: "field kind is not Enum".into(),
});
};
Ok(match values.iter().find(|(code, _)| *code == ret) {
Some((_, name)) => name.to_string(),
None => format!("{ret:02X}"),
})
}
// ------------------------------------------------------------------
// Writers
// ------------------------------------------------------------------
/// `i2c_byte` setter: validate byte range, `update = value & mask`, RMW.
pub fn write_byte(
&self,
conn: &mut Connection,
ctx: FieldContext,
value: u8,
) -> Result<(), FieldError> {
let unchanged = self.unchanged_part(conn, ctx)?;
self.write_one(conn, ctx, unchanged | (value & self.mask))
}
/// `i2c_bool` setter: set or clear the mask bits (always reads current).
pub fn write_bool(
&self,
conn: &mut Connection,
ctx: FieldContext,
value: bool,
) -> Result<(), FieldError> {
let current = self.read_one(conn, ctx)?;
let updated = if value { current | self.mask } else { current & !self.mask };
self.write_one(conn, ctx, updated)
}
/// `i2c_int` setter: validate `0..=(mask >> shift)`, shift into place, RMW.
pub fn write_int(
&self,
conn: &mut Connection,
ctx: FieldContext,
value: u8,
) -> Result<(), FieldError> {
let max = self.mask >> self.shift;
if value > max {
return Err(FieldError::InvalidValue {
value: value.to_string(),
reason: format!("not in valid range 0-{max}"),
});
}
let unchanged = self.unchanged_part(conn, ctx)?;
self.write_one(conn, ctx, unchanged | ((value << self.shift) & self.mask))
}
/// `i2c_enum` setter: name must be a member; write its code within the
/// mask, RMW otherwise.
pub fn write_enum(
&self,
conn: &mut Connection,
ctx: FieldContext,
name: &str,
) -> Result<(), FieldError> {
let Kind::Enum(values) = self.kind else {
return Err(FieldError::InvalidValue {
value: name.into(),
reason: "field kind is not Enum".into(),
});
};
let Some((code, _)) = values.iter().find(|(_, n)| *n == name) else {
return Err(FieldError::InvalidValue {
value: name.into(),
reason: "not a valid enum member".into(),
});
};
let unchanged = self.unchanged_part(conn, ctx)?;
self.write_one(conn, ctx, unchanged | (code & self.mask))
}
}
+22
View File
@@ -0,0 +1,22 @@
//! Slow-control register model for IGNITE64 boards.
//!
//! Slice 1 of the Board-model port (Open Point 3 in README):
//! * `fields` — Rust port of `innesco/ecs/_fields.py` (i2c_byte/enum/bool/int
//! descriptors, incl. their exact read-modify-write semantics);
//! * `board` — port of `innesco/ecs/board.py` (static board registers,
//! `config_crystal`);
//! * `pixel` — port of `innesco/ecs/pixel.py` (per-instance pixel registers,
//! finetune DAC nibble logic).
//!
//! Divergences from Python (see docs/porting-notes.md): the module-global
//! "current connection" is replaced by explicit `&mut Connection` arguments,
//! and `ValueError`/server errors are returned as `FieldError` instead of
//! raising.
mod board;
mod fields;
mod pixel;
pub use board::Board;
pub use fields::{FieldAddress, FieldContext, FieldError, I2cField, Kind};
pub use pixel::Pixel;
+133
View File
@@ -0,0 +1,133 @@
//! Rust port of `innesco/ecs/pixel.py` — per-instance pixel registers and
//! the finetune-DAC nibble logic.
use innesco_protocol::Connection;
use crate::fields::{FieldAddress, FieldContext, FieldError, I2cField};
/// One pixel of a mattonella: its registers live at
/// `(address = mattonella_id, subaddress = pixel_id)` (Python
/// `from_attribute("_mattonella_id")` / `("_pixel_id")`).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Pixel {
pub mattonella_id: u8,
pub pixel_id: u8,
}
impl Pixel {
pub const fn new(mattonella_id: u8, pixel_id: u8) -> Self {
Pixel { mattonella_id, pixel_id }
}
fn ctx(&self) -> FieldContext {
FieldContext { mattonella_id: self.mattonella_id, pixel_id: self.pixel_id }
}
/// Pixel power state (mask 0x40).
pub const POWER: I2cField = I2cField::bool_(
FieldAddress::MattonellaId,
Some(FieldAddress::PixelId),
0x40,
);
/// Pixel frontend state (mask 0x80).
pub const FRONTEND: I2cField = I2cField::bool_(
FieldAddress::MattonellaId,
Some(FieldAddress::PixelId),
0x80,
);
/// Pixel adjustment value (bits 5-4).
pub const ADJ: I2cField =
I2cField::int(FieldAddress::MattonellaId, Some(FieldAddress::PixelId), 4, 0x03);
/// Pixel control value (bits 3-0).
pub const CTRL: I2cField =
I2cField::int(FieldAddress::MattonellaId, Some(FieldAddress::PixelId), 0, 0x0F);
pub fn power(&self, conn: &mut Connection) -> Result<bool, FieldError> {
Self::POWER.read_bool(conn, self.ctx())
}
pub fn set_power(&self, conn: &mut Connection, on: bool) -> Result<(), FieldError> {
Self::POWER.write_bool(conn, self.ctx(), on)
}
pub fn frontend(&self, conn: &mut Connection) -> Result<bool, FieldError> {
Self::FRONTEND.read_bool(conn, self.ctx())
}
pub fn set_frontend(&self, conn: &mut Connection, on: bool) -> Result<(), FieldError> {
Self::FRONTEND.write_bool(conn, self.ctx(), on)
}
pub fn adj(&self, conn: &mut Connection) -> Result<u8, FieldError> {
Self::ADJ.read_int(conn, self.ctx())
}
pub fn set_adj(&self, conn: &mut Connection, value: u8) -> Result<(), FieldError> {
Self::ADJ.write_int(conn, self.ctx(), value)
}
pub fn ctrl(&self, conn: &mut Connection) -> Result<u8, FieldError> {
Self::CTRL.read_int(conn, self.ctx())
}
pub fn set_ctrl(&self, conn: &mut Connection, value: u8) -> Result<(), FieldError> {
Self::CTRL.write_int(conn, self.ctx(), value)
}
/// Finetune DAC of this pixel: two pixels share one register at
/// subaddress `0x4C + pixel_id / 2` (even pixel = low nibble, odd pixel =
/// high nibble) — Python `finetune_dac` property.
pub fn finetune_dac(&self, conn: &mut Connection) -> Result<u8, FieldError> {
let raw = Self::finetune_read(conn, self)?;
Ok(if self.pixel_id % 2 == 0 { raw } else { raw >> 4 } & 0x0F)
}
/// Finetune DAC setter (Python raises for values outside 0-15; here that
/// is a `FieldError::InvalidValue`).
pub fn set_finetune_dac(&self, conn: &mut Connection, value: u8) -> Result<(), FieldError> {
if value > 0x0F {
return Err(FieldError::InvalidValue {
value: value.to_string(),
reason: "out of valid range 0-15".into(),
});
}
let current = Self::finetune_read(conn, self)?;
let new_value = if self.pixel_id % 2 == 0 {
(current & 0xF0) | (value & 0x0F)
} else {
(current & 0x0F) | ((value & 0x0F) << 4)
};
Self::finetune_write(conn, self, new_value)
}
fn finetune_subaddress(&self) -> u8 {
0x4C + self.pixel_id / 2
}
fn finetune_read(conn: &mut Connection, px: &Pixel) -> Result<u8, FieldError> {
let resp = conn.send(&innesco_protocol::Request::ReadSub {
address: px.mattonella_id,
subaddress: px.finetune_subaddress(),
length: 1,
})?;
if resp.is_error() {
return Err(FieldError::Server { status: resp.status, message: resp.message() });
}
resp.i2c_data().first().copied().ok_or(FieldError::EmptyPayload)
}
fn finetune_write(conn: &mut Connection, px: &Pixel, value: u8) -> Result<(), FieldError> {
let resp = conn.send(&innesco_protocol::Request::WriteSub {
address: px.mattonella_id,
subaddress: px.finetune_subaddress(),
payload: vec![value],
})?;
if resp.is_error() {
return Err(FieldError::Server { status: resp.status, message: resp.message() });
}
Ok(())
}
}
+291
View File
@@ -0,0 +1,291 @@
//! Integration tests for the `innesco-ecs` register model.
//!
//! A minimal fake `data_server` keeps a register file in a HashMap keyed by
//! (address, subaddress): Reads return the stored byte, Writes store the
//! payload, Pings echo. This exercises the exact wire behaviour of the
//! read-modify-write semantics ported from `_fields.py`.
use std::collections::HashMap;
use std::io::{Read, Write};
use std::net::TcpListener;
use std::time::Duration;
use innesco_ecs::{Board, FieldContext, Pixel};
use innesco_protocol::Connection;
/// Fake data_server: HashMap register file + operation log.
struct FakeServer {
handle: std::thread::JoinHandle<()>,
port: u16,
/// shared state: register file (addr, sub) -> byte
regs: std::sync::Arc<std::sync::Mutex<HashMap<(u8, u8), u8>>>,
pings: std::sync::Arc<std::sync::Mutex<Vec<Vec<u8>>>>,
}
impl FakeServer {
fn start() -> Self {
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
let port = listener.local_addr().unwrap().port();
let regs = std::sync::Arc::new(std::sync::Mutex::new(HashMap::new()));
let pings = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
let (r, p) = (regs.clone(), pings.clone());
let handle = std::thread::spawn(move || {
let (mut sock, _) = listener.accept().unwrap();
loop {
let mut hdr = [0u8; 5];
if sock.read_exact(&mut hdr).is_err() {
break;
}
let opcode = hdr[0];
let len = u32::from_be_bytes([hdr[1], hdr[2], hdr[3], hdr[4]]) as usize;
let mut data = vec![0u8; len];
sock.read_exact(&mut data).unwrap();
match opcode {
0xC1 => {
p.lock().unwrap().push(data.clone());
let mut resp = vec![0u8];
resp.extend_from_slice(&(data.len() as u32).to_be_bytes());
resp.extend_from_slice(&data);
sock.write_all(&resp).unwrap();
}
0x10 | 0x12 => {
// Write: data = addr [, sub] payload
let (addr, sub, payload) = if opcode == 0x12 {
(data[0], data[1], &data[2..])
} else {
(data[0], 0xFF, &data[1..])
};
for (i, v) in payload.iter().enumerate() {
// No-subaddress ops address the register directly;
// multi-byte no-sub writes are not used by slice 1.
let s = if sub == 0xFF && i == 0 { 0xFF } else { sub };
r.lock().unwrap().insert((addr, s), *v);
}
sock.write_all(&[0, 0, 0, 0, 0]).unwrap();
}
0x11 | 0x13 => {
// Read: data = addr [, sub] len
let (addr, sub, length) = if opcode == 0x13 {
(data[0], data[1], u16::from_be_bytes([data[2], data[3]]))
} else {
(data[0], 0xFF, u16::from_be_bytes([data[1], data[2]]))
};
let mut payload = vec![0u8]; // i2c status
for _ in 0..length {
let s = if sub == 0xFF { 0xFF } else { sub };
let default = 0u8;
payload.push(*r.lock().unwrap().get(&(addr, s)).unwrap_or(&default));
}
let mut resp = vec![0u8];
resp.extend_from_slice(&(payload.len() as u32).to_be_bytes());
resp.extend_from_slice(&payload);
sock.write_all(&resp).unwrap();
}
_ => sock.write_all(&[1, 0, 0, 0, 4, b'e', b'r', b'r', b'!']).unwrap(),
}
}
});
FakeServer { handle, port, regs, pings }
}
fn connect(&self) -> Connection {
Connection::connect("127.0.0.1", self.port, Duration::from_secs(5)).unwrap()
}
fn get(&self, addr: u8, sub: u8) -> u8 {
*self.regs.lock().unwrap().get(&(addr, sub)).unwrap_or(&0)
}
fn set(&self, addr: u8, sub: u8, value: u8) {
self.regs.lock().unwrap().insert((addr, sub), value);
}
fn ping_count(&self) -> usize {
self.pings.lock().unwrap().len()
}
}
const CTX: FieldContext = FieldContext { mattonella_id: 0, pixel_id: 0 };
#[test]
fn mux_enum_roundtrip_and_rmw() {
let server = FakeServer::start();
let mut conn = server.connect();
// Empty register: writing NE (0x8, mask 0x0F) goes out as 0x08.
Board::MUX.write_enum(&mut conn, CTX, "NE").unwrap();
assert_eq!(server.get(0x70, 0xFF), 0x08);
assert_eq!(Board::MUX.read_enum(&mut conn, CTX).unwrap(), "NE");
// Preset the OTHER nibble: RMW must preserve it.
server.set(0x70, 0xFF, 0x40);
Board::MUX.write_enum(&mut conn, CTX, "SW").unwrap();
assert_eq!(server.get(0x70, 0xFF), 0x41);
// Invalid member is rejected client-side.
assert!(Board::MUX.write_enum(&mut conn, CTX, "NOPE").is_err());
// Unknown code falls back to the hex string (Python `enum.get(ret, ..)`).
server.set(0x70, 0xFF, 0x03);
assert_eq!(Board::MUX.read_enum(&mut conn, CTX).unwrap(), "03");
drop(conn); // close the connection so the fake server loop exits
server.handle.join().unwrap();
}
#[test]
fn board_0x20_sub_0x0a_fields() {
let server = FakeServer::start();
let mut conn = server.connect();
// FASTIN_SRC: J12=0x00 / LVDS=0xFF, mask 0x01 -> only bit 0 lands.
Board::FASTIN_SRC.write_enum(&mut conn, CTX, "LVDS").unwrap();
assert_eq!(server.get(0x20, 0x0A), 0x01);
// Faithful-to-Python quirk: LVDS=0xFF & mask 0x01 = 0x01, which is NOT an
// enum key, so the read falls back to the hex string "01" (the Python
// descriptor behaves identically; see docs/porting-notes.md).
assert_eq!(Board::FASTIN_SRC.read_enum(&mut conn, CTX).unwrap(), "01");
// EXTERNAL_DAC (mask 0x02) shares the same byte: preserve bit 0.
Board::EXTERNAL_DAC.write_enum(&mut conn, CTX, "OFF").unwrap();
assert_eq!(server.get(0x20, 0x0A), 0x03); // 0x01 | 0x02
// SI_CLK_IN uses mask 0x30: KRIA = 0x10.
Board::SI_CLK_IN.write_enum(&mut conn, CTX, "KRIA").unwrap();
assert_eq!(server.get(0x20, 0x0A), 0x13);
assert_eq!(Board::SI_CLK_IN.read_enum(&mut conn, CTX).unwrap(), "KRIA");
// ANALOG_POWER inverted encoding: ON=0x00 (clears bit 6), OFF=0x40.
Board::ANALOG_POWER.write_enum(&mut conn, CTX, "OFF").unwrap();
assert_eq!(server.get(0x20, 0x0A), 0x53);
assert_eq!(Board::ANALOG_POWER.read_enum(&mut conn, CTX).unwrap(), "OFF");
Board::ANALOG_POWER.write_enum(&mut conn, CTX, "ON").unwrap();
assert_eq!(server.get(0x20, 0x0A), 0x13);
assert_eq!(Board::ANALOG_POWER.read_enum(&mut conn, CTX).unwrap(), "ON");
// SEL_DATA_EN_SRC mask 0x04: J14=0xFF & 0x04 = 0x04 -> hex fallback "04"
// on read (same non-round-trip quirk as FASTIN_SRC; Python-identical).
Board::SEL_DATA_EN_SRC.write_enum(&mut conn, CTX, "J14").unwrap();
assert_eq!(server.get(0x20, 0x0A), 0x17);
assert_eq!(Board::SEL_DATA_EN_SRC.read_enum(&mut conn, CTX).unwrap(), "04");
// SI_CLK_OE mask 0x08.
Board::SI_CLK_OE.write_enum(&mut conn, CTX, "ON").unwrap();
assert_eq!(server.get(0x20, 0x0A), 0x1F);
drop(conn); // close the connection so the fake server loop exits
server.handle.join().unwrap();
}
#[test]
fn direction_register_full_byte() {
let server = FakeServer::start();
let mut conn = server.connect();
// i2c_byte with mask 0xFF: write without prior read, full byte.
Board::DIRECTION_REGISTER.write_byte(&mut conn, CTX, 0xA5).unwrap();
assert_eq!(server.get(0x20, 0x00), 0xA5);
// The getter returns the RAW byte (mask not applied) — Python quirk kept.
assert_eq!(Board::DIRECTION_REGISTER.read_byte(&mut conn, CTX).unwrap(), 0xA5);
drop(conn); // close the connection so the fake server loop exits
server.handle.join().unwrap();
}
#[test]
fn pixel_bools_share_one_byte() {
let server = FakeServer::start();
let mut conn = server.connect();
let px = Pixel::new(5, 3); // registers at (0x05, 0x03)
px.set_power(&mut conn, true).unwrap();
assert_eq!(server.get(0x05, 0x03), 0x40);
px.set_frontend(&mut conn, true).unwrap();
assert_eq!(server.get(0x05, 0x03), 0xC0);
// power still true after touching frontend
assert!(px.power(&mut conn).unwrap());
assert!(px.frontend(&mut conn).unwrap());
px.set_power(&mut conn, false).unwrap();
assert_eq!(server.get(0x05, 0x03), 0x80);
assert!(!px.power(&mut conn).unwrap());
assert!(px.frontend(&mut conn).unwrap());
drop(conn); // close the connection so the fake server loop exits
server.handle.join().unwrap();
}
#[test]
fn pixel_adj_ctrl_int_fields() {
let server = FakeServer::start();
let mut conn = server.connect();
let px = Pixel::new(0, 7);
// ADJ mask 0x03 shift 4, CTRL mask 0x0F shift 0: same byte, RMW combines.
px.set_adj(&mut conn, 2).unwrap();
assert_eq!(server.get(0x00, 0x07), 0x20);
px.set_ctrl(&mut conn, 9).unwrap();
assert_eq!(server.get(0x00, 0x07), 0x29);
assert_eq!(px.adj(&mut conn).unwrap(), 2);
assert_eq!(px.ctrl(&mut conn).unwrap(), 9);
// Range checks (Python ValueError).
assert!(px.set_adj(&mut conn, 4).is_err());
assert!(px.set_ctrl(&mut conn, 16).is_err());
drop(conn); // close the connection so the fake server loop exits
server.handle.join().unwrap();
}
#[test]
fn pixel_finetune_dac_nibbles() {
let server = FakeServer::start();
let mut conn = server.connect();
// Even pixel (id 2): low nibble of register 0x4C + 1 = 0x4D.
let even = Pixel::new(1, 2);
even.set_finetune_dac(&mut conn, 7).unwrap();
assert_eq!(server.get(0x01, 0x4D), 0x07);
assert_eq!(even.finetune_dac(&mut conn).unwrap(), 7);
// Odd pixel (id 3): high nibble of the SAME register.
let odd = Pixel::new(1, 3);
odd.set_finetune_dac(&mut conn, 12).unwrap();
assert_eq!(server.get(0x01, 0x4D), 0xC7); // 0x0C << 4 | 0x07
assert_eq!(even.finetune_dac(&mut conn).unwrap(), 7); // untouched
assert_eq!(odd.finetune_dac(&mut conn).unwrap(), 12);
// Out of range (Python ValueError "out of valid range 0-15").
assert!(Pixel::new(1, 2).set_finetune_dac(&mut conn, 16).is_err());
drop(conn); // close the connection so the fake server loop exits
server.handle.join().unwrap();
}
#[test]
fn config_crystal_parses_and_writes() {
let server = FakeServer::start();
let mut conn = server.connect();
let path = std::env::temp_dir().join("innesco-rs-crystal-test.cfg");
std::fs::write(
&path,
"# comment\n\n0x0140, 0x2A\n0x0201, 0xFF\nNOT A LINE\n0x0302,0x7F\n",
)
.unwrap();
let n = Board::config_crystal(&path, &mut conn).unwrap();
assert_eq!(n, 3);
// Register address high byte -> sub 0x01, value -> sub (addr & 0xFF).
// Note: row 2 (0x0201) writes its lo byte (0xFF) to sub 0x01, then row 3
// rewrites sub 0x01 with hi=0x03 — the final hi is 0x03.
assert_eq!(server.get(0x75, 0x01), 0x03);
assert_eq!(server.get(0x75, 0x40), 0x2A);
assert_eq!(server.get(0x75, 0x02), 0x7F);
// Two pings bracket the sequence.
assert_eq!(server.ping_count(), 2);
let _ = std::fs::remove_file(&path);
drop(conn); // close the connection so the fake server loop exits
server.handle.join().unwrap();
}
+14
View File
@@ -35,6 +35,20 @@
addresses (which is exactly where the Python `ix/iy` shadowing bug lived —
not reproduced here; see `_bindings.py` history in the original repo).
## Faithful-port findings (bugs/quirks in the original, mirrored exactly)
7. **`i2c_enum` codes do not always round-trip through the getter.** The
Python setter writes `enum_code & mask`, but several enums define codes
wider than their mask (`fastin_src` LVDS=0xFF with mask 0x01,
`external_dac` OFF=0xFF/0x02, `sel_data_en_src` J14=0xFF/0x04,
`si_clk_oe` ON=0xFF/0x08). After such a write, the masked read yields a
code that is not an enum key, so the getter returns the hex fallback
(e.g. `"01"`) instead of the name. The Rust port reproduces this exactly;
a future cleanup (agreed to be deferred) would store masked codes.
8. **`config_crystal` hi/lo aliasing**: the high byte of each register
address is written to subaddress 0x01 of the controller (0x75), so a row
whose low byte IS 0x01 overwrites the next row's hi byte. Mirrored as-is.
## Domain constants (kept identical)
- Quadrants: NE=0, SE=1, SW=2, NW=3 (`decoding.c` defines).