Replace Aquilon full-store downloads with targeted AWJ reads

This commit is contained in:
Dandaedre 2026-11-15 14:17:35 +01:00
parent 1c88944d1d
commit b4dacb23ea
11 changed files with 856 additions and 372 deletions

View File

@ -221,6 +221,14 @@ pub fn fetch(host: &str) -> Result<Snapshot, String> {
pub fn fetch_cancellable(
host: &str,
cancelled: &std::sync::atomic::AtomicBool,
) -> Result<Snapshot, String> {
fetch_with_awj_port(host, cancelled, 10606)
}
pub(crate) fn fetch_with_awj_port(
host: &str,
cancelled: &std::sync::atomic::AtomicBool,
awj_port: u16,
) -> Result<Snapshot, String> {
if cancelled.load(std::sync::atomic::Ordering::Relaxed) {
return Err("Device read cancelled.".into());
@ -246,8 +254,8 @@ pub fn fetch_cancellable(
cancelled,
)?,
Profile::Aquilon6 => state::fetch(
&client,
&format!("http://{authority}/api/stores/device"),
SocketAddr::new(authority.ip(), awj_port),
&identity,
cancelled,
)?,
};

File diff suppressed because it is too large Load Diff

View File

@ -344,11 +344,16 @@ fn execute(plan: &Plan, transport: &mut impl Transport) -> Result<Snapshot, Stri
}
struct Connection {
host: String,
awj_port: u16,
socket: Option<tungstenite::WebSocket<TcpStream>>,
}
impl Transport for Connection {
fn read(&mut self) -> Result<Snapshot, String> {
device::fetch(&self.host)
device::fetch_with_awj_port(
&self.host,
&std::sync::atomic::AtomicBool::new(false),
self.awj_port,
)
}
fn write(&mut self, change: &Change) -> Result<(), String> {
if self.socket.is_none() {
@ -380,8 +385,16 @@ impl Transport for Connection {
/// Explicit send: write fields, pulse preset xUpdate, then verify geometry readback.
/// Banks are pinned; another controller's TAKE can change their on-air role.
pub fn send(host: &str, plan: &Plan) -> Result<Snapshot, String> {
send_with_awj_port(host, plan, 10606)
}
pub(crate) fn send_with_awj_port(
host: &str,
plan: &Plan,
awj_port: u16,
) -> Result<Snapshot, String> {
let mut connection = Connection {
host: host.trim().into(),
awj_port,
socket: None,
};
let fresh = connection.read()?;
@ -442,7 +455,11 @@ mod tests {
let message = socket.read().unwrap();
serde_json::from_str::<Value>(message.to_text().unwrap()).unwrap()
});
let mut connection = Connection { host, socket: None };
let mut connection = Connection {
host,
awj_port: 10606,
socket: None,
};
connection
.write(&Change {
path: vec!["test".into()],

View File

@ -294,115 +294,6 @@ fn cancellation_does_not_contact_device() {
);
}
#[test]
fn mock_http_websocket_send_preflights_applies_and_reads_back_without_routing() {
use std::{
io::{BufRead, BufReader, Write},
net::{TcpListener, TcpStream},
time::{Duration, Instant},
};
fn accept(listener: &TcpListener) -> TcpStream {
let deadline = Instant::now() + Duration::from_secs(8);
loop {
match listener.accept() {
Ok((s, _)) => {
s.set_read_timeout(Some(Duration::from_secs(5))).unwrap();
return s;
}
Err(e) if e.kind() == std::io::ErrorKind::WouldBlock => {
assert!(Instant::now() < deadline, "mock server timed out");
std::thread::sleep(Duration::from_millis(10));
}
Err(e) => panic!("{e}"),
}
}
}
fn http(listener: &TcpListener, expected: &str, body: &Value) {
let mut stream = accept(listener);
let mut reader = BufReader::new(stream.try_clone().unwrap());
let mut line = String::new();
reader.read_line(&mut line).unwrap();
assert_eq!(line, format!("GET {expected} HTTP/1.1\r\n"));
loop {
line.clear();
reader.read_line(&mut line).unwrap();
if line == "\r\n" {
break;
}
}
let body = body.to_string();
write!(
stream,
"HTTP/1.1 200 OK\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
body.len()
)
.unwrap();
}
let raw = routed();
let state = Snapshot::parse(&identity(), &raw).unwrap();
let mut layout = Layout::default();
layout
.apply(
0,
Geometry {
x: 12.125,
y: 34.375,
width: 301.25,
height: 251.5,
},
)
.unwrap();
let plan = Plan::prepare(
&state,
&layout,
0,
&[(layout.layer_info(0).id, "1".into())],
Target::Preview,
Sizing::SourceAspect,
)
.unwrap();
let changes = plan.changes.len();
let listener = TcpListener::bind("127.0.0.1:0").unwrap();
listener.set_nonblocking(true).unwrap();
let host = listener.local_addr().unwrap().to_string();
let server = std::thread::spawn(move || {
let mut raw = raw;
http(&listener, "/api/tpp/v1/system", &identity());
http(&listener, "/api/stores/device", &raw);
let mut ws = tungstenite::accept(accept(&listener)).unwrap();
let mut paths = vec![];
for i in 0..changes + 2 {
let message = ws.read().unwrap();
let message: Value = serde_json::from_str(message.to_text().unwrap()).unwrap();
assert_eq!(message["channel"], "DEVICE");
let path = message["data"]["path"]
.as_array()
.unwrap()
.iter()
.map(|s| s.as_str().unwrap())
.collect::<Vec<_>>()
.join("/");
let after = &message["data"]["value"];
if i >= changes {
assert_eq!(path, "device/screenAuxGroupList/control/pp/xUpdate");
assert_eq!(after, &json!(i == changes + 1));
}
assert!(
!path.contains("xTake") && !path.contains("source/") && !path.contains("inputList")
);
*raw.pointer_mut(&format!("/{path}")).unwrap() = after.clone();
paths.push(path);
}
http(&listener, "/api/tpp/v1/system", &identity());
http(&listener, "/api/stores/device", &raw);
paths
});
let result = canvas_pilot::device_send::send(&host, &plan);
let paths = server.join().unwrap();
assert!(result.is_ok(), "{result:?}");
assert_eq!(paths.len(), changes + 2);
}
#[test]
fn documented_v13_example_contains_native_aquilon_link() {
let p = Project::from_json(include_str!(

View File

@ -8,6 +8,6 @@ S1 has seven allocated numbered layers; its stored eighth slot tests allocation
filtering. S2 and A1 are disabled. Test code creates explicit synthetic variations
for active auxiliaries, canvas changes, bank swaps and malformed fields.
The full 118 MiB response remains a private temporary artifact. The runtime
projection and parser both exercise this fixture; live write/restore diagnostics
The full 118 MiB response remains a private temporary artifact. The targeted-read collector and parser exercise this fixture; test helpers
add collection keys and identity fields for the mock AWJ endpoint; live write/restore diagnostics
are separate examples, never CI tests.

View File

@ -8,7 +8,7 @@ user-provided custom port. See the [current adapter contract](../interfaces/devi
## Current acceptance
- Identity, bounded full-store streaming projection, screen/layer allocations and
- Identity, bounded targeted AWJ reads, screen/layer allocations and
Preview/Program transition-group resolution work on the emulator.
- Twelve apply/readback/import cases pass: Preview and Program × Output-sized and
Source aspect × three fractional/portrait/asymmetric crop cases (zoom 1, 2 and 4).
@ -28,7 +28,7 @@ user-provided custom port. See the [current adapter contract](../interfaces/devi
WebSocket/apply behavior. Auxiliaries are tested with sanitized synthetic state;
this emulator's baseline only allocates S1.
- Workspace tests, Clippy, formatting and warning-free Rust documentation pass;
all 62 Python checks pass. Full application line coverage is 90.53%.
all 62 Python checks pass. Full application line coverage is 90.69%.
- Linked units, older firmware, other models, physical output and advanced shared
input correction are not claimed as verified. Masks and non-centered fit modes
remain explicit import limitations, not silently approximated geometry.
@ -39,6 +39,24 @@ to LIVE_1 in both banks; production sends never route. A separate
`--visual-check-and-restore` mode holds a known Preview layout for 60 seconds for
WebRCS inspection, then restores it. These diagnostics are never automated CI tests.
## Targeted read performance follow-up
The initial full-store reader has been replaced by batched property reads on
AWJ TCP 10606. The configured HTTP port still handles identity, captures and
WebSocket writes. The [adapter contract](../interfaces/device-adapters.md) records
framing, bounds, endpoint requirements and the consistency check.
Measured on the same emulator: 197180 AWJ response bytes + 124 HTTP identity bytes,
184978 request bytes, and direct reads of 0.314 / 0.302 / 0.297 seconds. The earlier
store was 124077157 bytes, so downloaded payload fell by 99.84%. A counting proxy
confirmed no `/api/stores/device` request. All twelve Preview/Program send cases
passed again with targeted preflight/readback, and the current baseline was restored.
The current manufacturer AWJ V6.2 and REST v6.0 PDFs were accessible using literal
`+` URL path segments; the percent-encoded links returned 403. AWJ property and
collection reads were verified directly. The historical full-store investigation
below describes the earlier implementation, not the current connection path.
## Historical protocol investigation
The following records the investigation before implementation; its future-tense

View File

@ -1,6 +1,7 @@
# Aquilon / LivePremier support — agent handoff
Status: **initial standalone AQL Cmax 6.2 adapter implemented**. See
Status: **initial standalone AQL Cmax 6.2 adapter implemented**, now using
batched targeted AWJ reads instead of full-store downloads. See
[acceptance and limitations](aquilon-compatibility.md) and the
[adapter contract](../interfaces/device-adapters.md). The checklist below is the
original implementation brief, retained for the remaining unverified profiles and

View File

@ -4,6 +4,8 @@
## Unreleased
- Replace Aquilon full-store downloads with batched AWJ reads on TCP 10606, retaining fresh preflight and verified sends. Emulator reads fell from 124 MB to about 197 KB and took about 0.30 seconds directly. Twelve transfer cases passed with restoration; malformed/incomplete responses and changing snapshots fail explicitly. HTTP/WebSocket custom ports remain supported; AWJ must be reachable on the same IP.
- Replace unsupported arrow glyphs in transfer labels and help text with plain text so they render with the bundled UI font.
- Add a separate Aquilon / LivePremier 6.2 adapter around a shared screen/layer model, with bounded cancellable state reads, allocated-slot discovery, explicit bank roles, fractional geometry and centered crop/zoom transfer, and input previews above 16. Sends preflight conversion inputs and bank roles, apply the correct family pulse and verify readback. Twelve emulator Preview/Program geometry/crop cases passed with baseline restoration; device writes round sizes/centers to whole pixels because WebRCS rejects fractional fields despite firmware accepting them. The initial profile targets standalone AQL Cmax; linked systems, other firmware/models and unsupported fit/input-correction modes remain explicit limitations.

View File

@ -7,8 +7,9 @@
Enter an IP address in **Device IP / port**, optionally followed by a TCP port:
`192.168.10.146:3000`. Without a port, the app uses port 80. IPv6 addresses
with a port use brackets, for example `[::1]:3000`. Omit URL schemes and paths.
The same address is saved in preferences and used for reads, input snapshots,
automatic reconnect and WebSocket sends.
The address is saved in preferences and used for identity, input snapshots,
automatic reconnect and WebSocket sends. Aquilon also requires AWJ TCP port
10606 on the same IP for its targeted geometry reads; Midra reads use the HTTP port.
Use **Recent machines…** to switch to one of the last four successful connections.
Choosing an entry connects immediately to read its state; it does not send layers.
@ -179,10 +180,12 @@ reported explicitly when their visible bounds cannot be imported. Shared input
correction controls remain managed in WebRCS for this adapter. Ordinary sends
never route inputs, TAKE, or change shared input processing.
The 118 MiB emulator state is streamed through a bounded projection on a worker.
Connection/read cancellation discards results and stops subsequent reads; a
blocked network read can take until its timeout. Input snapshots retain the same
Aquilon reads only the required properties through AWJ TCP 10606, in batches,
including a consistency check. The tested emulator now downloads about 197 KB
per refresh instead of 124 MB, with direct reads around 0.30 seconds. Preflight
and verification use the same targeted reader. If the AWJ port is disabled or
blocked, the connection reports an error instead of falling back to the full
store. Connect, load and send remain background operations. Input snapshots retain
pooled, throttled, opt-in behavior, including inputs above 16. Older firmware,
linked units and other Aquilon models are not enabled without adapter validation.
See the [adapter contract](../../interfaces/device-adapters.md) for tested scope,
limits and protocol details.
linked units and other Aquilon models remain unverified. See the
[adapter contract](../../interfaces/device-adapters.md) for tested scope and limits.

View File

@ -67,7 +67,7 @@ device readback and physical-screen acceptance.
## Remaining feature work
- [x] **Aquilon / LivePremier adapter (standalone AQL Cmax 6.2).** Device-neutral snapshots, family-aware v13 links, bounded state projection, geometry/crop import, mapped Preview/Program sends and pooled input previews. See [adapter contract](../interfaces/device-adapters.md) and [emulator acceptance](aquilon-compatibility.md). Linked units, other models/firmware, shared input corrections and non-centered/masked import remain explicitly unsupported.
- [x] **Aquilon / LivePremier adapter (standalone AQL Cmax 6.2).** Device-neutral snapshots, family-aware v13 links, bounded targeted AWJ reads, geometry/crop import, mapped Preview/Program sends and pooled input previews. See [adapter contract](../interfaces/device-adapters.md) and [emulator acceptance](aquilon-compatibility.md). Linked units, other models/firmware, shared input corrections and non-centered/masked import remain explicitly unsupported.
- [ ] **Further export/workflow cleanup.** Shared transfer scopes, mapping review
and direct linked send/load are implemented; further changes await specifications.

View File

@ -15,21 +15,43 @@ profiles do not support linked-unit identity; linked Aquilon devices are refused
## Aquilon profile and reads
Initial profile: standalone **AQL Cmax, firmware 6.2.x**, exercised on **6.2.79**.
Other firmware/models are rejected before downloading the state. `/api/tpp/v1/system`
supplies identity; `/api/stores/device` supplies native state. The emulator has
authentication disabled. Authenticated devices currently report their HTTP/auth
failure rather than saving credentials or attempting a login.
Other firmware/models are rejected before reading geometry. `/api/tpp/v1/system`
on the configured HTTP port supplies identity. Aquilon geometry uses **AWJ TCP
10606 on the same IP**, independently of the HTTP/WebSocket port. AWJ model and
firmware are checked against the HTTP identity. A blocked/disabled AWJ port is an
explicit connection error; there is no full-store HTTP fallback. Midra retains
its existing HTTP reader. The emulator has authentication disabled; HTTP auth
failures remain explicit and credentials are not saved.
No smaller supported read route was found in the installed WebRCS client. Tested
`/api/stores/device/device/screenList/items/S1/status` and
`/api/device/screenList/items/S1/status` return 404. The fallback streams the
observed 124,077,157-byte store with a **160 MiB** wire limit, **one million**
decoded nodes, **16 MiB** aggregate retained/key text budget, **1024 bytes** per
string, **256 entries** per retained map/array, and bounded nesting. Unrelated
trees are skipped rather than materialized. Unallocated layers and disabled
screens are removed before the snapshot is retained. Network connection timeout
is 5 seconds; request timeout is 45 seconds. Worker cancellation is checked
between reads; a blocked read retains its timeout. No state enters project files.
The [manufacturer's AWJ guide V6.2](https://dwn01.analogway.com/Site+Internet/Series/Aquilon/Common/AWJ+Protocol/AW_Aquilon_AWJ_ProgrammersGuide_V6.2.pdf)
documents property reads over TCP. Requests are `{"op":"get","path":"..."}`,
terminated by byte `0x04`. Canonical paths start with `DeviceObject`; list,
item and property segments use `$screen`, `@items` and `@props`. Responses are
matched by exact canonical path, including out-of-order replies. Error, missing,
unexpected, duplicate, truncated and oversized responses fail the read.
Reads discover `itemKeys`, then screen modes and available inputs. Only enabled
screens, their allocated numbered layers in the two current role banks, active
input plugs, framing settings and snapshot availability are requested. No memory
banks, inactive layer slots, hardware inventories or other large subtrees are read.
These targeted values populate the same normalized adapter state as before.
Requests are pipelined in batches of **64**; parent-object reads are avoided because
the emulator returns empty objects for them. A second pass compares all selected
values, including topology and bank roles; a changing snapshot is rejected instead
of being used for a send. No cache, persistent subscription or AWJ writes are used.
Bounds: **256** entries per discovered collection, **65536** selected fields,
**16 KiB** per response, and **16 MiB** aggregate response bytes across both passes.
TCP connect/write timeout is **3 seconds**, collection deadline **30 seconds**,
and read waits check cancellation at **250 ms** intervals. HTTP identity retains
its 5-second connect / 45-second request limits. All work stays on the worker.
On the 6.2.79 emulator, a complete two-pass read received **197180 bytes** over
AWJ plus **124 bytes** of HTTP identity, versus the previous **124077157-byte**
store download: **99.84% less downloaded payload**. AWJ requests totalled 184978
bytes. Three direct debug-build reads took **0.314, 0.302 and 0.297 seconds**;
a counting proxy took 1.601 seconds. These are local emulator measurements,
excluding TCP/HTTP header overhead, not guarantees for every device configuration.
Enabled `screenList` and `auxiliaryList` entries supply `status.pp.layerCount`
(0–128) and `status.size.pp.sizeH/sizeV`. Canvas dimensions also obey editor