Return to Garage

Net OS WOLF-E 0.3 — architecture and operating contract

19 November 2026. Candidate release, WOLF-E 01. Core 0.3.0-core.rc3, Pilot bundled with Core, Eye 50 / 0.3.0-eye.rc1, Garage 0.3.0-garage.rc1, telemetry API 1.2.0. This is an inspectable software candidate, not a certification of autonomous corridor driving. Earlier manual demonstrations are retained as demonstrations. Mission 0, 1 and 2 require physical acceptance tests before autonomous operation can be described as proven.

Net OS components and control authorityBounded autonomous decision cycle

1. Read by responsibility

Operator: use Pilot, Mission 0, confirmation at A, persistent launch diagnostics and independent Stop. Review Sessions and the video timeline in Garage.
Electrical engineer: use Core Energy for PMIC rails, input voltage, power flags, USB allowance, Eye battery gauge and the source-labelled bench protocol. Passport contains declared hardware and unknowns.
Software engineer: follow the component map, protocols, folders, contracts, deployment and tests below. Drive is the sole actuator owner.
Researcher: retain native sensor rates, immutable video, operator annotations and versioned map provenance. A command is not a distance measurement; a range fan is not an independent 3D map.
Product/fleet owner: maintain the versioned passport, capabilities and mission acceptance record. A new chassis requires its own commissioned mapping and limits.

2. System and authority

Net OS is the general ecosystem. Sentinel is the future shared C2 planning/integration layer. Pilot is the local operator application; Core is the onboard processing and control stack; Eye is the Android sensor/camera, character and internet relay; Garage is the cloud observation, evidence, configuration and research workspace.

Hardware → acquisition → timestamped observations → estimation / mission decision → Drive broker → ordinary Pixhawk arming and mapped PWM outputs → FT85BS controllers → wheels.

Pilot → local HTTP session → Launch → Confirm → Drive. Stop has an independent path. Garage has observation, annotations, passport revisions and proposals; it cannot send arbitrary motor commands. Eye voice is optional and does not bypass local launch confirmation. USB attachment and software restart never arm the vehicle.

Actual implementation is Python plus browser JavaScript/HTML/CSS, Node.js gateways and Java Android. The driving UI is not React. ROS 2 and MAVROS are provisioned for telemetry interoperability; they are not a second actuator owner. Pixhawk is currently ArduPilot Rover 4.7.1 over MAVLink serial. No firmware flash or hidden parameter change is part of 0.3.

3. Components and physical folders

Repository: work/net-os. apps/edge/edge/drive contains core.py (authority, leases, ramp/deadman), pixhawk.py (MAVLink transport and commissioned output checks), server.py (broker routes and snapshots), pilot.py (mode/settings), frame_trial.py (bounded trials), mapped_mission.py (registered mission state machine), pose_estimator.py, route_driver.py and decision_record.py (estimation, candidate decisions and audit), journal.py, imu_log.py and cloud_archive.py (durability and relay).

apps/edge/edge/sensors contains phone_usb.py and usb_wire.py (Android accessory framing), core_health.py (passive boot-wide health), camera/vision acquisition and supporting services. edge/ros contains sensor/ROS telemetry bridges. edge/server is the Node local gateway. edge/public is Pilot, Core, Energy and planning UI. system contains systemd units; scripts contains guarded release packaging/updating; verification contains synthetic API, timing, state and transport tests.

apps/companion contains native Android Java sources, resources and the offline signed APK build script. CoreService owns sharing; UsbSensorLink carries framed USB data; PhoneEnergy reads battery properties; CloudLink owns bounded uploads; ServiceCues and GazePolicy drive display/sounds, never chassis tracking.

apps/wolf-cloud/server contains the Node telemetry API, append-only object store, media assembly, access checks and passport/annotation validation. public contains the static Garage, Three.js model/cloud viewer, telemetry/video charts, research reports and per-second frame derivatives. tools/field-kit contains capture, COLMAP reconstruction and range-response tooling. docs/release-0.3 contains this contract and requirements/qualification notes. .local holds private credentials, profiles, backups, APK signing material and investigation evidence; never commit or publish it.

On Pi: /opt/netos/releases/<version>, /opt/netos/current symlink; /etc/netos is private commissioning/configuration; /var/lib/netos-drive retains journal, controller captures, trials, map attempts and outbox; /var/lib/netos-health retains one observation log per Linux boot. /run/netos-phone, /run/netos-edge, /run/netos-health and /run/netos-drive contain transient snapshots/sockets. Runtime files are not a durable archive.

4. Interfaces and clocks

Pilot/Core browser uses local HTTP through the gateway. Local operator sessions are bearer capabilities with sequence numbers, enable IDs and held-input semantics. The Drive Unix socket is /run/netos-drive/drive.sock. The broker, not the browser or cloud, owns command deadlines, neutral/stop and controller state. core.local and pilot.local are mDNS aliases; direct field fallback is 192.168.50.1 on the configured Pi AP, or the configured administrative Ethernet IP 192.168.77.2. Names and AP credentials remain installation configuration; do not embed the Wi-Fi password in public documentation.

Eye ↔ Core uses wired Android Open Accessory with WUSB type/length/sequence frames. Sensor packets are fast; reporting frames are 1 Hz. PILOT7 fragments observations; ARCHIVE_PAGE carries independent bounded archive pages so backlog cannot monopolize a live snapshot. MEDIA9 transfers evidence clips. EyeEnergy carries battery-side gauge values; MasterM0 carries a bounded cached passport declaration. These metadata messages cannot arm or command motors. Frame size, finite-number and stale-packet checks apply.

TF03 uses the existing UART driver and validated serial frames. Pixhawk uses MAVLink USB serial. A heartbeat proves communication, not motor battery connection or available traction. The hardware safety switch and ordinary firmware arming checks remain authoritative. MAIN OUT 1 left pair / MAIN OUT 2 right pair is the operator-confirmed current wiring; four controllers do not imply four independently controlled channels or four wheel odometers.

Core → Eye → cloud uses finite HTTPS /api/v1/sync requests with device-scoped upload credentials. One-Hz health samples are archived in batches at approximately ten-second transfer intervals; active live snapshots remain one Hz. Records are acknowledged only after durable storage. Duplicate identical IDs are idempotent; conflicting content is rejected. Media uploads use bounded chunks, SHA-256 completion and byte-range playback. Phone internet is the normal field relay; unplugging it leaves Core durable logs pending. Resumption does not mean old data is live.

Core monotonic time defines command intervals. Eye wall-clock/elapsed anchors date and align observations. An unsynchronized Pi calendar is preserved but not used as proof of field date. Same-capture interpolation is labelled; do not extrapolate one offset across unrelated reboots. Missing IMU, camera or phone data remains a gap, not repeated fresh telemetry.

5. Data and cloud contract

The database is a structured append-only object archive plus local SQLite journals, not a relational cloud SQL deployment. Local raw captures remain unchanged. Cloud bucket: osnova-496915-wolf-e-telemetry in project osnova-496915. Private raw backups are raw/wolf-e/<day>/; immutable telemetry is devices/<device>/sessions/<session>/; catalogue and fleet receipt indexes serve discovery; media and media-index store clip payloads and manifests. Review frames are versioned derivatives under reports/<day>/media. Access credentials and device identities stay outside public reports.

A day contains awakenings, physical activity groups and original source records. Reconnects, arming refusals and power interruptions stay within the activity; they do not each become a new successful drive. All-day playback and all original leases remain available alongside provisional groupings. Current known place, command source, measured/synthetic provenance, firmware/software versions, clock basis and uncertainty belong to every mission attempt context.

A frame decision stores the observed sensor timestamps, commanded impulse, accepted versus reported output, estimated pose/covariance, range target association, visual residual, selected candidate, rejected alternatives and stop reason. Front/rear proof images share the phone timeline. Full-rate traces remain separate from downsampled chart previews. Operators can add immutable labels/comments and time intervals without altering raw evidence.

Cloud Run engagement is for finite upload/read requests. No always-on simulator or permanent WebSocket is needed for Garage live watch. A visible, bounded watch lease requests approximately one-second observations while active; hidden/expired views stop polling. Online does not guarantee zero latency: show capture age and durable receipts. Keep min instances zero, request-based CPU and bounded instance/concurrency/timeout settings. Browser chart/3D rendering is local; reconstruction is an explicit offline job.

6. Energy and instrumentation

Current reference: native Raspberry Pi mains adapter. Keep battery/converter tests in separately tagged windows. PMIC ADC exposes rail voltage/current pairs and EXT5V voltage. Sum of PMIC rail output watts excludes USB/GPIO demand and conversion loss; it is not total input watts. Total 5 V input current, per-port USB current, motor current, pack state of charge and torque are unknown without external instrumentation. BATT is the Pi RTC battery rail.

Eye reports voltage, battery percentage/temperature/status, instantaneous/average battery current, charge counter and supported energy counter. Android positive current means net charging, negative means net discharge. At 100% charge, near-zero battery current does not prove near-zero USB power. Unsupported gauge values remain null. Eye camera processing is included in Eye's engineering allowance; do not add camera and battery-side power again to USB input.

Engineering allowance: Pi compute 4–12 W, Eye USB 0–4.5 W, Pixhawk 2–2.5 W (provisional allowance), TF03 ≤1 W and ≤150 mA at 5 V (operator-supplied specification). Combined upper allowance 20 W, about 4 A at 5 V, before margins and future lighting; it is not a measured consumption. TF03's 150 mA is 0.75 W, so the 1 W ceiling is a conservative separate specification. Shared USB allowance and supply capacity must both be checked. PSU_MAX_CURRENT=5000 declares supply capability; it does not create current or repair voltage drop.

The current traction declaration is BT-E6000 36 V, 11.6 Ah, 417.6 Wh nominal; chemistry/SOC require verification. Planned four 3.2 V 105 Ah cells form 12.8 V, 1344 Wh nominal if series-connected; this is not installed hardware. Two 2.5 V LEDs cannot be budgeted from voltage alone: obtain rated current, driver/resistor and relay coil/contact specifications. Future IR wavelength must match camera sensitivity and an appropriate driver. Relay/LED loads remain outside today's measured budget.

Bench protocol: motors physically disconnected; unchanged Pi/phone/TF03/Pixhawk, then 60 seconds sharing + both cameras, 60 seconds cameras off, optional measured USB dummy load, and a separately labelled battery-converter repeat. Capture input voltage, active/historical flags, temperature, per-core load, disk and USB resets, Pixhawk board voltage, Eye gauge, freshness and dropouts. A CPU stress workload cannot simulate electrical USB load. A volt/amp meter is needed to close the energy budget.

7. Awakening and CONOPS

Power on → observe connected equipment → standby, guarded/unarmed. The phone can retain its awakening session through Core restarts. Pixhawk appearance triggers status/character cues, not propulsion. Driver battery presence cannot be proved from USB communication; the movement test proves only collective mobility when observed displacement is credible.

Mission 0, readiness: confirm fixed, aligned mounts and clear space; Launch → Confirm movement check, default 18% / 1 s, up to three identical bounded attempts when no response is measured. Then calibration: up to five 18% / 0.7 s pulses, neutral and observation between pulses, early stop at 0.80 m motor-only beam delta. Measure actual stopped travel, manually complete the marked 1 m endpoint and save it separately. No automatic effort escalation. A beam hitting a different object must not become a calibration distance.

Mission 1, straight corridor: operator places centred at A and explicitly confirms place/heading. A→C is zero heading in the local mission frame; raw yaw remains retained. Confirmed doorway/back-wall association determines route distance; 20 m is provisional. Observe → estimate → forecast → choose bounded impulse → neutral → reobserve. AB, BC, CB and BA each have ≤10 actions; C and A turns each ≤5, maximum 50. Effort/duration are editable within commissioned bounds and changes apply after neutral. Action budget is not a promise of distance or completion time. Stop/physical takeover remains available.

Mission 2, extended corridor and turns: ABCDEF → FEDCBA, parquet and constrained doors. Requires a reviewed metric route, turning footprint, registered opposite-direction camera coverage and stopping validation. Current reconstructed fragments are partial, not a complete qualified map.

Mission 3, outdoor route: asphalt, holes and slopes require a surveyed perimeter, depth/obstacle evidence, tilt/roll monitoring, GPS quality and braking tests. A gravity vector estimates attitude relative to vertical; it does not measure altitude. A single forward beam cannot certify ground support or side/rear free space.

Mission 4, pitlane return: manual or pushed departure/return demonstrations produce route evidence. Narrow-door clearance and pose confidence must be validated before autonomous return. Pitstop recognition is a proposal until confirmed; a familiar image alone does not prove exact docking pose.

8. Estimation, terrain intelligence and learning

Use calibrated Pixhawk attitude/gyro as the onboard primary reference, Eye as an independently timestamped secondary reference with explicit mounting transform. Compare relative yaw, rate and acceleration residuals; do not average incompatible axes. Linear acceleration excludes estimated gravity but still contains bias/vibration. Magnetometer is optional where motor/steel interference is rejected. Indoor GPS is place context, not centimetre localization.

A Kalman-style prediction/correction state tracks pose, velocity and uncertainty. Visual map registration corrects position; accepted IMU updates attitude; a forward range update is conditional on its expected target. The longest beam and a roughly 1.95 m open-door range jump are useful associations, not proof: another surface, doorway state, person or angle can produce similar readings. Range endpoints are translated into a corridor only when pose registration is valid; otherwise display a labelled polar response fan with unknown translation.

Forecast five one-second frames using the current conditional state and uncertainty. Choose among forward, reverse, left/right correction, neutral or hold only when the predicted swept footprint and stopping margin are supportable. Recalculate after each bounded action. Missing/contradictory evidence increases uncertainty and can require hold; it must not be relabelled exact position merely because the rover is on leg AB. No 100% navigation guarantee is made.

Learning in 0.3 is measured response calibration and evidence comparison: impulse duration/effort, terrain label, response latency, stopped displacement, heading change and coasting. It is not online neural reinforcement learning. Low movement can indicate low effort, blocked drive, slipping wheels or a changed range target; without wheel feedback the system cannot identify which wheel slipped. Automatic model promotion requires repeatable measured outcomes and explicit review.

9. Map/reconstruction lifecycle

Record front/rear video plus native telemetry → retain immutable source hashes → choose sharp overlapping frames → COLMAP features/matching/SfM → inspect registered views and reprojection evidence → metric scale from measured correspondences → align synthetic route/reconstruction and camera extrinsics → qualify live localization → test manually → replay decisions → promote a versioned mission pack.

Keep synthetic geometry, reconstructed camera landmarks and sensor response layers independent. Each revision records source day/drive/clip hashes, intrinsics, units, scale evidence, transform, quality, limitations and parent version. Retain previous revisions for side-by-side comparison. Never silently fuse unrelated unscaled fragments or label a single-beam fan a LiDAR scan. Front/back phone cameras are not a calibrated stereo rig. The HELLA/CountBOX sensor is not an enabled depth source until powered, identified and its stream/API is verified.

A mission pack contains route/waypoints/forbidden zones, footprint/mounts, synthetic model, selected reconstruction/range revisions, camera intrinsics/extrinsics, metric transforms, launch context, allowed action bounds, stop rules, evidence schema and acceptance criteria. Pack readiness is distinct from operator place confirmation. Display precision bands as centimetres / decimetres / metres / tens of metres only from supported uncertainty, not desired accuracy.

10. Security, deployment and rollback

Per-device upload keys, administrator-read access and a separate operations-admin write capability are different roles. Passport updates and interval annotations need the write capability; it is held in browser memory after explicit file import. Credentials never appear in the BOM or public reports. The current archive audience policy is inherited from the existing laboratory deployment; do not treat unguessable URLs as authentication or claim production identity/RBAC is complete.

Package a new version and SHA256SUMS. Back up consistent SQLite, raw logs and private configuration first. Install over SSH using netos-update only with verified disabled/disarmed state. The updater verifies file hashes, rejects unsafe archives, preserves configuration/data, keeps the prior release and restarts in disabled bench mode. Linux serial PTY tests are required for Pixhawk transport changes. No transport/firmware change was made for 0.3.

Cloud API: deploy apps/wolf-cloud through the existing Google project/region, retaining bucket and secrets, min0 and bounded max instances. Garage: deploy the separate Cloudflare Worker config wrangler.garage-3.jsonc; older Garage origins remain. Android: signed versioned APK; keep the same signing identity. Verify health/version, both camera freshness, power semantics, durable receipt and archive replay after deployment. Rollback only while disabled/disarmed using the retained prior app release; preserve new evidence and configuration compatibility. Automatic fleet OTA and signed device enrollment remain roadmap items, not delivered capabilities.

11. Acceptance and roadmap

0.3 software acceptance: observer never opens serial or actuates; partial/malformed archive lines do not wedge transfer; durable receipts gate completion; old Eye remains compatible; input-left cannot inherit stale throttle; M0 action/distance budgets are bounded; A is accepted as an operator place record without fabricating map registration; stale power values are hidden; archive/video gaps remain visible; passport writes cannot use legacy read credentials.

Physical acceptance still required: stable battery/converter power with all USB equipment, actual motor direction verification on the stand, neutral/braking/coast envelope, M0 measured calibration, registered forward/return localization, corridor boundary/turn clearance and manual takeover. A release candidate may improve diagnostics without being ready for unattended autonomy.

0.4: external battery/USB current instrumentation and BMS, properly driven visible/IR illumination with lux thresholds/hysteresis, camera response verification, authenticated updates and collaboration up to four qualified vehicles. Followers require separation, communications-loss and independent-stop behavior; do not reuse a single-rover route as a collision guarantee.

0.5: commissioned profiles for Bull-E, Monstr-E, Bugg-E, Duck-E and prospective Fish-E; larger payload/braking, marine/underwater sensing and hardware-specific acceptance. Shared contracts stay reusable, physical assumptions do not.

References

Raspberry Pi PMIC and vcgencmd: https://www.raspberrypi.com/documentation/computers/os.html
Raspberry Pi power documentation: https://www.raspberrypi.com/documentation/hardware/raspberrypi/power.html
Android battery property units and charging direction: https://developer.android.com/reference/android/os/BatteryManager.html
ArduPilot motor/output configuration: https://docs.ardupilot.org/rover/docs/rover-motor-and-servo-configuration.html
COLMAP workflow: https://colmap.github.io/tutorial.html
Source of implementation claims: repository modules listed above, verified 19 November backup and release test receipts. Operator observations remain labelled separately from sensor-derived findings.