From 7d0ad8f9c165f0a9b2209d75354f6465e416dbd6 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 7 Nov 2026 22:43:41 +0000 Subject: [PATCH] Add a supervised iPhone and UNO R4 cane demo. Separate hazard, unavailable, and manual route cues from a board-side link watchdog, and test that the camera path cannot invent an obstacle distance or a safe direction. Co-authored-by: pschmeln --- .github/workflows/workflow-check.yml | 6 +- .gitignore | 3 + AGENTS.md | 2 +- README.md | 6 +- docs/COLLABORATION.md | 6 +- docs/PROTOTYPE.md | 140 +++++++ prototype/Makefile | 14 + prototype/firmware/uno_r4_wifi/cane_logic.c | 306 +++++++++++++++ prototype/firmware/uno_r4_wifi/cane_logic.h | 167 ++++++++ .../firmware/uno_r4_wifi/uno_r4_wifi.ino | 119 ++++++ .../CaneDemo.xcodeproj/project.pbxproj | 280 ++++++++++++++ .../xcshareddata/xcschemes/CaneDemo.xcscheme | 76 ++++ .../CaneDemo/CaneDemo-Bridging-Header.h | 1 + .../ios/CaneDemo/CaneDemo/CaneDemoApp.swift | 12 + .../ios/CaneDemo/CaneDemo/DebugRootView.swift | 138 +++++++ .../CaneDemo/CaneDemo/DemoController.swift | 360 ++++++++++++++++++ prototype/ios/CaneDemo/CaneDemo/Info.plist | 51 +++ prototype/tests/test_cane.c | 297 +++++++++++++++ scripts/check_workflow.py | 5 +- 19 files changed, 1980 insertions(+), 9 deletions(-) create mode 100644 docs/PROTOTYPE.md create mode 100644 prototype/Makefile create mode 100644 prototype/firmware/uno_r4_wifi/cane_logic.c create mode 100644 prototype/firmware/uno_r4_wifi/cane_logic.h create mode 100644 prototype/firmware/uno_r4_wifi/uno_r4_wifi.ino create mode 100644 prototype/ios/CaneDemo/CaneDemo.xcodeproj/project.pbxproj create mode 100644 prototype/ios/CaneDemo/CaneDemo.xcodeproj/xcshareddata/xcschemes/CaneDemo.xcscheme create mode 100644 prototype/ios/CaneDemo/CaneDemo/CaneDemo-Bridging-Header.h create mode 100644 prototype/ios/CaneDemo/CaneDemo/CaneDemoApp.swift create mode 100644 prototype/ios/CaneDemo/CaneDemo/DebugRootView.swift create mode 100644 prototype/ios/CaneDemo/CaneDemo/DemoController.swift create mode 100644 prototype/ios/CaneDemo/CaneDemo/Info.plist create mode 100644 prototype/tests/test_cane.c diff --git a/.github/workflows/workflow-check.yml b/.github/workflows/workflow-check.yml index a33a20c..16a4274 100644 --- a/.github/workflows/workflow-check.yml +++ b/.github/workflows/workflow-check.yml @@ -1,5 +1,5 @@ -# Checks collaboration docs, templates, and local links. -# It does not install dependencies, read secrets, or run application tests. +# Checks collaboration docs and runs the host cane-logic tests. +# It does not install dependencies, read secrets, compile iOS, or flash hardware. name: Workflow scaffolding @@ -20,3 +20,5 @@ jobs: uses: actions/checkout@v4 - name: Validate scaffolding run: python3 scripts/check_workflow.py + - name: Run host logic tests + run: make -C prototype test diff --git a/.gitignore b/.gitignore index 46df433..2650d8c 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,6 @@ CLAUDE.local.md # Local Python bytecode from the workflow checker __pycache__/ *.pyc + +# Host test binary +prototype/build/ diff --git a/AGENTS.md b/AGENTS.md index c71a57e..1d68a71 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Cursor agent instructions -MakeUC Hackathon 2026. No product, stack, or app is chosen. Read and follow [the collaboration workflow](docs/COLLABORATION.md) before editing. If this file and that guide disagree, follow the guide and update this file in the same pull request. +MakeUC Hackathon 2026. The current demo scope is [docs/PROTOTYPE.md](docs/PROTOTYPE.md). Read and follow [the collaboration workflow](docs/COLLABORATION.md) before editing. If this file and that guide disagree, follow the guide and update this file in the same pull request. You are Grok Bot when you coordinate work, and the Cursor coding agent when you implement a task. You handle Cursor sessions, including [cloud agents](https://cursor.com/docs/cloud-agent). A human starts any Claude Code session separately. No automatic handoff from this agent to Claude Code is configured. diff --git a/README.md b/README.md index 8178fb1..f9da7d0 100644 --- a/README.md +++ b/README.md @@ -5,4 +5,8 @@ MakeUC Hackathon 2026 Shared instructions for the owner, one teammate, Cursor, and Claude Code: [docs/COLLABORATION.md](docs/COLLABORATION.md). -No product or stack is defined yet. +## Prototype + +Supervised iPhone 16 and UNO R4 WiFi cane demo: [docs/PROTOTYPE.md](docs/PROTOTYPE.md). + +Host logic tests, with no phone or board required: `make -C prototype test`. diff --git a/docs/COLLABORATION.md b/docs/COLLABORATION.md index 3da9812..0d8e3e0 100644 --- a/docs/COLLABORATION.md +++ b/docs/COLLABORATION.md @@ -1,6 +1,6 @@ # Collaboration workflow -MakeUC Hackathon 2026. This repository is the shared coordination space for the owner, one human teammate, Grok Bot in Cursor, and Claude Code. No product, stack, or app is chosen. Add application code, dependencies, or product requirements only after a human writes them in a task. +MakeUC Hackathon 2026. This repository is the shared coordination space for the owner, one human teammate, Grok Bot in Cursor, and Claude Code. The supervised demo scope is [the prototype](PROTOTYPE.md). Further product scope still comes from a human task. Cursor loads a short operating card in [`AGENTS.md`](../AGENTS.md). Claude Code loads this guide through the import in [`CLAUDE.md`](../CLAUDE.md). @@ -58,7 +58,7 @@ Keep each pull request to one task. A reviewer should be able to check the diff GitHub fills in [`.github/PULL_REQUEST_TEMPLATE.md`](../.github/PULL_REQUEST_TEMPLATE.md) for new pull requests once the template is on the default branch, `main`. -In the pull request, name the review steps and the command you ran. The automated check in this repository validates workflow files. It is not an application test suite. +In the pull request, name the review steps and the command you ran. The automated check validates these workflow files and runs the host cane-logic tests. It does not compile the iOS app, flash the board, or certify the demo as safe. The author opens the pull request and stops. A human merges. Prefer approval from a human who did not author the change. When the other person is unavailable, the repository owner may merge and records that on the pull request. An agent is not an approver. @@ -133,7 +133,7 @@ Issue and pull request template behavior is documented in [About issue and pull - [`.github/ISSUE_TEMPLATE/task.md`](../.github/ISSUE_TEMPLATE/task.md) for a task. - [`.github/PULL_REQUEST_TEMPLATE.md`](../.github/PULL_REQUEST_TEMPLATE.md) for a pull request. - [`scripts/check_workflow.py`](../scripts/check_workflow.py) checks these files, local links, the Claude Code import, and the workflow syntax this repo can parse without added packages. -- [`.github/workflows/workflow-check.yml`](../.github/workflows/workflow-check.yml) runs that script with Python 3 already on the GitHub-hosted runner and GitHub's `actions/checkout` action at major version 4. The workflow installs nothing and reads no secrets. +- [`.github/workflows/workflow-check.yml`](../.github/workflows/workflow-check.yml) runs that script, then `make -C prototype test`, with Python 3 and a C compiler already on the GitHub-hosted runner and GitHub's `actions/checkout` action at major version 4. The workflow installs nothing and reads no secrets. After changing any of these files, run this from the repository root: diff --git a/docs/PROTOTYPE.md b/docs/PROTOTYPE.md new file mode 100644 index 0000000..7e43bb2 --- /dev/null +++ b/docs/PROTOTYPE.md @@ -0,0 +1,140 @@ +# Supervised cane demo + +This is a controlled demo for MakeUC Hackathon 2026. A sighted supervisor wears or mounts a standard iPhone 16 so its rear camera faces the direction of travel, and an Arduino UNO R4 WiFi drives four external actuators on an existing cane. The cane remains the mobility aid. This demo is not a replacement cane, not unsupervised guidance, and not a test to run with a blind traveler. + +The phone warns with uncertainty. It does not invent a safe path. A quiet hazard channel is not an all-clear. + +## Fixed demo requirements + +- The phone is body-mounted. This repository does not design the mount. +- Four actuator channels are separate sensations. The firmware drives four logic outputs. Placement on the cane is part of the build, not a steering map. +- Destination guidance is not in this increment. A manual demo label can mark left or right on the route channel. That label does not mean the direction is clear. + +## What the hardware can and cannot do + +Apple's [iPhone 16 technical specifications](https://www.apple.com/iphone-16/specs/) list the sensors as Face ID, barometer, gyro, accelerometer, proximity, and ambient light. That list does not include a LiDAR scanner. The phone has a rear dual camera and motion sensors. + +ARKit scene depth is documented as a LiDAR measurement. Apple says to call `supportsFrameSemantics(_:)` before enabling it, and that scene depth is supported only on LiDAR-capable devices: [sceneDepth](https://developer.apple.com/documentation/arkit/arconfiguration/framesemantics-swift.struct/scenedepth). This app checks that flag and does not enable scene depth, even if some other device reports support. + +World tracking is a separate capability. The app calls `ARWorldTrackingConfiguration.isSupported` and requests camera permission at runtime: [Verifying device support and user permission](https://developer.apple.com/documentation/arkit/verifying-device-support-and-user-permission). Apple's [Understanding world tracking](https://developer.apple.com/documentation/arkit/understanding-world-tracking) describes a right-handed camera coordinate system. Apple's [Displaying an AR Experience with Metal](https://developer.apple.com/documentation/arkit/displaying-an-ar-experience-with-metal) sample treats a camera-relative translation of 0.2 as 0.2 meters. When tracking is normal, this demo reports the distance between consecutive ARKit camera positions as an ARKit camera step in those units. It is device motion, not an obstacle distance and not a speed. It was not calibrated on a physical iPhone 16 here. + +An object detector is not used. A box in the image does not provide meters. + +No monocular depth network is bundled. A relative-depth model would not be an honest meter reading, and this environment cannot validate a metric model or its license on an iPhone 16. + +The app can raycast the center of the frame against ARKit's existing detected planes ([planeDetection](https://developer.apple.com/documentation/arkit/arworldtrackingconfiguration/planedetection-swift.struct)). A hit is the distance from the current camera pose to that plane, shown as context. It does not raise a hazard and it is not a clearance. No hit stays unknown. Plane detection on this iPhone was not run here. + +The UNO R4 WiFi uses a Renesas RA4M1 for the headers and an ESP32-S3-MINI-1-N8 for wireless. The [datasheet](https://docs.arduino.cc/resources/datasheets/ABX00087-datasheet.pdf) says the RA4M1 GPIOs can safely handle up to 8 mA, and that higher-current devices such as servo motors need an external supply. The [cheat sheet](https://docs.arduino.cc/tutorials/uno-r4-wifi/cheat-sheet) says the ESP32-S3 provides Bluetooth LE and Wi-Fi, and that those radios share one antenna, so they are not used at the same time. [ArduinoBLE](https://docs.arduino.cc/libraries/arduinoble/) documents peripheral and central modes and names the UNO R4 WiFi. The library README requires ESP32-S3 firmware 0.2.0 or newer for that board. This firmware is a BLE peripheral only. It does not join Wi-Fi. The iPhone is the BLE central through [Core Bluetooth](https://developer.apple.com/documentation/corebluetooth). + +## Camera path and simulation path + +Every outgoing packet has one source. + +The camera path can report tracking, an ARKit camera step, and an optional plane-hit context. Its hazard claim is always "no claim", and its route cue is always none. If camera permission, world tracking, or normal tracking is missing, the system-unavailable channel is on. Missing scene depth does not by itself mean unavailable, and it also does not create a distance. + +The simulation path is a separate control on the phone. It can request an elevated hazard, a system-unavailable cue, and a demo left or right label. The screen says the input is simulated. Those controls do not read the camera. The shared encoder rejects a camera-sourced hazard or a camera-sourced route cue, so a buggy packet of that shape does not move the actuators. + +There is no random left or right choice. Nothing in the camera path picks a direction. + +## Four channels + +| Output | Pin | Meaning while the link is alive | +| --- | --- | --- | +| Hazard | D2 | Pulses only for an elevated claim. Off is not an all-clear. | +| System unavailable | D3 | Pulses when the selected source says the pipeline cannot support a claim. | +| Route demo | D4 | Pulses for a manual left or right label. The label is on the phone and in the claim. The pulse does not mean that side is safe. | +| Link | D5 | Board-owned. A short blip every 2 seconds means packets are arriving. A fast, mostly-on pattern means the watchdog expired. | + +The programmed watchdog is 500 ms after the last valid packet, using the board's `millis()`. At 500 ms the link is still a heartbeat. At 501 ms it is an outage. During an outage the board forces D2, D3, and D4 off and keeps the outage pattern on D5. A rejected packet does not refresh the watchdog. Before the first valid packet, the board is already in outage. + +Silence on all four outputs means the board is unpowered, the firmware is not running, or the drivers are disconnected. That is a fault, not a clear path. + +The patterns are different periods in code so a supervisor can tell the channels apart. Whether a particular actuator feels distinct is a bench check, not a result recorded here. + +## Actuator wiring + +Each GPIO only enables an external driver. It does not power the actuator. + +For each channel: + +1. Use a low-side switch the builder has checked for a 5 V logic input and for the actuator's current. +2. Put the actuator between the external supply positive and the switch. Put the switch between the actuator and the common ground. +3. Connect the GPIO to the switch input through a series resistor. Add a pulldown so a reset or floating pin stays off. +4. If the actuator is inductive, put a flyback diode across it, cathode toward the supply. +5. Tie the external supply ground to a UNO ground. Do not feed actuator current through the header pin. +6. Do not connect 5 V signals to the ESP32-S3 header. Those pins are 3.3 V. + +Power the actuators from a supply that can provide their current. The datasheet's 8 mA GPIO limit is for the logic pin, not a budget for the motor. + +## BLE packets + +Service `8f3a1c20-7b6e-4d5a-9c11-6e2f0a9b1001`. + +Command characteristic `8f3a1c20-7b6e-4d5a-9c11-6e2f0a9b1002`, 18 bytes, written by the phone. The layout, CRC-16/CCITT-FALSE, and admissibility rules live in [cane_logic.h](../prototype/firmware/uno_r4_wifi/cane_logic.h). Eighteen bytes fits a 20-byte default BLE write. The link has no pairing secret. Turn the board off when the demo is finished. Do not treat the advertisement as an access-controlled safety channel. + +Status characteristic `8f3a1c20-7b6e-4d5a-9c11-6e2f0a9b1003`, 8 bytes, notified by the board. The phone shows it as controller status. Until a notification arrives, the phone does not know the pin state. + +The phone timer asks to send about ten times a second. That is the timer interval in [DemoController.swift](../prototype/ios/CaneDemo/CaneDemo/DemoController.swift). It is not a measured radio or actuator latency. + +## What is implemented + +- Host-tested assessment, packet, watchdog, and output logic. +- UNO R4 WiFi sketch that advertises `CaneDemo`, accepts command packets, and drives D2-D5. +- iPhone app source: camera preview, capability checks, ARKit world tracking, camera-step readout, existing-plane context, simulation controls, and a BLE central. +- Shared rejection of camera hazards and camera route cues. + +## What is not implemented + +- A meter distance to an arbitrary obstacle, a velocity, or a time to contact. +- A depth model, object detector, or use of scene depth. +- Automatic avoidance, including a random direction. +- Maps, destinations, or turn-by-turn guidance. +- A designed body mount, driver board, or chosen actuator part. +- Proof that four actuators feel distinct. +- A measured end-to-end latency. +- BLE pairing. +- An iOS binary or a flashed board. This environment has no Xcode and no Arduino toolchain. + +## Checks that were run here + +From the repository root: + +```bash +make -C prototype test +python3 scripts/check_workflow.py +``` + +`make` compiles `cane_logic.c` with the host C compiler and runs [test_cane.c](../prototype/tests/test_cane.c). Those tests do not open a camera, a radio, or a GPIO. They do not pass if they are described as an iOS or hardware result. + +## Build the iPhone app + +Use a Mac with Xcode 16 or newer and an iOS 18 SDK. + +1. Open [CaneDemo.xcodeproj](../prototype/ios/CaneDemo/CaneDemo.xcodeproj/project.pbxproj) in Xcode. +2. Select the CaneDemo target, then Signing & Capabilities. Choose your Apple ID team. The project does not contain a team id. +3. Change the bundle id `com.makeuc2026.canedemo` if your team cannot use it. +4. Connect the standard iPhone 16, trust the computer, and enable Developer Mode. +5. Run on that device. The simulator does not stand in for this phone's camera, motion, or a BLE peripheral. +6. Confirm the debug screen. On a standard iPhone 16, scene depth support should read no. If it reads yes, stop and treat the device as the wrong model. This build still does not enable scene depth. + +## Flash the UNO R4 WiFi + +1. Install Arduino IDE 2. +2. Install the Arduino UNO R4 Boards package and select Arduino UNO R4 WiFi. +3. Install ArduinoBLE from the Library Manager. Use a release that lists UNO R4 WiFi, and update the board so the ESP32-S3 bridge firmware is 0.2.0 or newer if the board package asks. +4. Open [uno_r4_wifi.ino](../prototype/firmware/uno_r4_wifi/uno_r4_wifi.ino) and upload it. +5. Open Serial Monitor at 115200. Before the phone connects, the log should show the link outage pattern. The sketch was not compiled in this environment. + +## Supervised demo + +Do this with a sighted supervisor, in a clear space, with the existing cane still used as the cane. Stop if anyone would have to rely on the actuators to move safely. + +1. Mount the phone so the rear camera faces travel. Connect the four drivers before powering the actuators. +2. Flash the board and confirm the link channel is in its outage pattern while the phone is disconnected. +3. Launch the app, accept camera and Bluetooth prompts, and wait until the phone says the link is ready. +4. Read the camera section. Tracking can be normal while the hazard line still says no claim. Walk a few steps and watch the camera-step line change only while tracking stays normal. That number is the phone's motion. +5. Switch the outgoing source to Simulation. The banner must say the input is simulated. Turn on the elevated hazard and confirm D2 pulses while D5 stays in the heartbeat pattern. Turn on the unavailable cue and confirm D3 can pulse at the same time. Choose a left or right label and confirm D4 pulses. The label is only a label. +6. Force the link to drop by quitting the app or moving out of range. D2, D3, and D4 should go off, and D5 should change to the fast outage pattern. Powering the board off should silence every channel. Silence is a fault. +7. To measure latency, record one video of the phone screen and the actuator, or of the screen and the serial log. Switch the simulated hazard. The latency is the time from the on-screen claim change to the actuator or log change. Write down the number you observe. This repository does not provide one. + +The serial `ms=` value is the board's `millis()` when the output state changes. Packet acceptance and pin updates happen in the same loop, so that log is not the phone-to-actuator delay. diff --git a/prototype/Makefile b/prototype/Makefile new file mode 100644 index 0000000..8b14259 --- /dev/null +++ b/prototype/Makefile @@ -0,0 +1,14 @@ +CC ?= cc +CFLAGS ?= -std=c11 -Wall -Wextra -Werror -I firmware/uno_r4_wifi + +.PHONY: test clean + +test: build/test_cane + ./build/test_cane + +build/test_cane: firmware/uno_r4_wifi/cane_logic.c firmware/uno_r4_wifi/cane_logic.h tests/test_cane.c + mkdir -p build + $(CC) $(CFLAGS) -o $@ firmware/uno_r4_wifi/cane_logic.c tests/test_cane.c -lm + +clean: + rm -rf build diff --git a/prototype/firmware/uno_r4_wifi/cane_logic.c b/prototype/firmware/uno_r4_wifi/cane_logic.c new file mode 100644 index 0000000..c00a0cc --- /dev/null +++ b/prototype/firmware/uno_r4_wifi/cane_logic.c @@ -0,0 +1,306 @@ +#include "cane_logic.h" + +#include + +static int finite_f(float value) { + return value == value && value < 1000000.0f && value > -1000000.0f; +} + +static uint16_t read_le16(const uint8_t *bytes) { + return (uint16_t)bytes[0] | ((uint16_t)bytes[1] << 8); +} + +static uint32_t read_le32(const uint8_t *bytes) { + return (uint32_t)bytes[0] | ((uint32_t)bytes[1] << 8) | ((uint32_t)bytes[2] << 16) | + ((uint32_t)bytes[3] << 24); +} + +static void write_le16(uint8_t *bytes, uint16_t value) { + bytes[0] = (uint8_t)(value & 0xFFu); + bytes[1] = (uint8_t)((value >> 8) & 0xFFu); +} + +static void write_le32(uint8_t *bytes, uint32_t value) { + bytes[0] = (uint8_t)(value & 0xFFu); + bytes[1] = (uint8_t)((value >> 8) & 0xFFu); + bytes[2] = (uint8_t)((value >> 16) & 0xFFu); + bytes[3] = (uint8_t)((value >> 24) & 0xFFu); +} + +uint16_t cane_crc16(const uint8_t *data, size_t len) { + uint16_t crc = 0xFFFFu; + size_t i; + int bit; + for (i = 0; i < len; i++) { + crc ^= (uint16_t)data[i] << 8; + for (bit = 0; bit < 8; bit++) { + if ((crc & 0x8000u) != 0) { + crc = (uint16_t)((crc << 1) ^ 0x1021u); + } else { + crc = (uint16_t)(crc << 1); + } + } + } + return crc; +} + +static void clear_plane(cane_assessment_t *out) { + out->plane_hit_valid = 0; + out->plane_hit_cm = CANE_PLANE_CM_NONE; +} + +static void record_plane(const cane_input_t *in, cane_assessment_t *out) { + float centimeters; + if (!in->has_plane_hit || in->tracking != CANE_TRACKING_NORMAL || !finite_f(in->plane_hit_meters)) { + clear_plane(out); + return; + } + if (!(in->plane_hit_meters > 0.0f) || in->plane_hit_meters > (CANE_PLANE_CM_MAX / 100.0f)) { + clear_plane(out); + return; + } + centimeters = in->plane_hit_meters * 100.0f; + if (!finite_f(centimeters)) { + clear_plane(out); + return; + } + out->plane_hit_valid = 1; + out->plane_hit_cm = (uint16_t)(centimeters + 0.5f); + if (out->plane_hit_cm == 0 || out->plane_hit_cm > CANE_PLANE_CM_MAX) { + clear_plane(out); + } +} + +void cane_assess(const cane_input_t *in, cane_assessment_t *out) { + out->source = in->source; + out->tracking = in->tracking; + out->scene_depth_supported = in->scene_depth_supported ? 1 : 0; + out->hazard = CANE_HAZARD_NO_CLAIM; + out->system_unavailable = 1; + out->route_cue = CANE_ROUTE_NONE; + record_plane(in, out); + + if (in->source == CANE_SOURCE_CAMERA) { + int pipeline_ready = in->camera_authorized && in->world_tracking_supported && + in->tracking == CANE_TRACKING_NORMAL; + out->system_unavailable = pipeline_ready ? 0 : 1; + out->hazard = CANE_HAZARD_NO_CLAIM; + out->route_cue = CANE_ROUTE_NONE; + return; + } + + if (in->source == CANE_SOURCE_SIMULATION) { + out->hazard = in->simulation_elevated_hazard ? CANE_HAZARD_ELEVATED : CANE_HAZARD_NO_CLAIM; + out->system_unavailable = in->simulation_unavailable ? 1 : 0; + if (in->route_cue == CANE_ROUTE_DEMO_LEFT || in->route_cue == CANE_ROUTE_DEMO_RIGHT) { + out->route_cue = in->route_cue; + } + } +} + +int cane_camera_displacement_m( + float x0, + float y0, + float z0, + float x1, + float y1, + float z1, + int tracking_normal, + float *meters_out) { + float dx; + float dy; + float dz; + float squared; + if (!tracking_normal || meters_out == NULL) { + return 0; + } + if (!finite_f(x0) || !finite_f(y0) || !finite_f(z0) || !finite_f(x1) || !finite_f(y1) || !finite_f(z1)) { + return 0; + } + dx = x1 - x0; + dy = y1 - y0; + dz = z1 - z0; + if (!finite_f(dx) || !finite_f(dy) || !finite_f(dz)) { + return 0; + } + squared = (dx * dx) + (dy * dy) + (dz * dz); + if (!finite_f(squared) || squared < 0.0f) { + return 0; + } + *meters_out = sqrtf(squared); + return finite_f(*meters_out); +} + +void cane_command_from_assessment( + const cane_assessment_t *assessment, + uint32_t sequence, + uint16_t time_ms_low, + cane_command_t *command) { + command->source = assessment->source; + command->hazard = assessment->hazard; + command->system_unavailable = assessment->system_unavailable ? 1 : 0; + command->route_cue = assessment->route_cue; + command->tracking = assessment->tracking; + command->scene_depth_supported = assessment->scene_depth_supported ? 1 : 0; + command->plane_hit_cm = assessment->plane_hit_valid ? assessment->plane_hit_cm : CANE_PLANE_CM_NONE; + command->sequence = sequence; + command->time_ms_low = time_ms_low; +} + +int cane_command_admissible(const cane_command_t *command) { + if (command->source != CANE_SOURCE_CAMERA && command->source != CANE_SOURCE_SIMULATION) { + return 0; + } + if (command->hazard != CANE_HAZARD_NO_CLAIM && command->hazard != CANE_HAZARD_ELEVATED) { + return 0; + } + if (command->system_unavailable != 0 && command->system_unavailable != 1) { + return 0; + } + if (command->route_cue != CANE_ROUTE_NONE && command->route_cue != CANE_ROUTE_DEMO_LEFT && + command->route_cue != CANE_ROUTE_DEMO_RIGHT) { + return 0; + } + if (command->tracking < CANE_TRACKING_UNSUPPORTED || command->tracking > CANE_TRACKING_NORMAL) { + return 0; + } + if (command->source == CANE_SOURCE_CAMERA) { + if (command->hazard != CANE_HAZARD_NO_CLAIM || command->route_cue != CANE_ROUTE_NONE) { + return 0; + } + } + return 1; +} + +int cane_command_encode(const cane_command_t *command, uint8_t out[CANE_PACKET_BYTES]) { + uint16_t crc; + if (!cane_command_admissible(command)) { + return 0; + } + out[0] = CANE_PACKET_VERSION; + out[1] = (uint8_t)command->source; + out[2] = (uint8_t)command->hazard; + out[3] = (uint8_t)command->system_unavailable; + out[4] = (uint8_t)command->route_cue; + out[5] = (uint8_t)command->tracking; + out[6] = command->scene_depth_supported ? 1u : 0u; + out[7] = 0; + write_le32(&out[8], command->sequence); + write_le16(&out[12], command->time_ms_low); + write_le16(&out[14], command->plane_hit_cm); + crc = cane_crc16(out, 16); + write_le16(&out[16], crc); + return 1; +} + +int cane_command_decode(const uint8_t *bytes, size_t len, cane_command_t *command) { + uint16_t expected; + uint16_t actual; + if (len != CANE_PACKET_BYTES || bytes[0] != CANE_PACKET_VERSION || bytes[7] != 0) { + return 0; + } + expected = cane_crc16(bytes, 16); + actual = read_le16(&bytes[16]); + if (expected != actual) { + return 0; + } + command->source = bytes[1]; + command->hazard = bytes[2]; + command->system_unavailable = bytes[3]; + command->route_cue = bytes[4]; + command->tracking = bytes[5]; + command->scene_depth_supported = bytes[6] ? 1 : 0; + command->sequence = read_le32(&bytes[8]); + command->time_ms_low = read_le16(&bytes[12]); + command->plane_hit_cm = read_le16(&bytes[14]); + return cane_command_admissible(command); +} + +void cane_link_init(cane_link_t *link) { + link->last_valid_ms = 0; + link->have_valid = 0; + link->command.source = CANE_SOURCE_CAMERA; + link->command.hazard = CANE_HAZARD_NO_CLAIM; + link->command.system_unavailable = 1; + link->command.route_cue = CANE_ROUTE_NONE; + link->command.tracking = CANE_TRACKING_UNAVAILABLE; + link->command.scene_depth_supported = 0; + link->command.plane_hit_cm = CANE_PLANE_CM_NONE; + link->command.sequence = 0; + link->command.time_ms_low = 0; +} + +int cane_link_accept(cane_link_t *link, const uint8_t *bytes, size_t len, uint32_t now_ms) { + cane_command_t command; + if (!cane_command_decode(bytes, len, &command)) { + return 0; + } + link->command = command; + link->have_valid = 1; + link->last_valid_ms = now_ms; + return 1; +} + +int cane_pulse(uint32_t now_ms, uint32_t period_ms, uint32_t on_ms) { + if (period_ms == 0 || on_ms == 0) { + return 0; + } + return (now_ms % period_ms) < on_ms; +} + +static int link_outage(const cane_link_t *link, uint32_t now_ms) { + if (!link->have_valid) { + return 1; + } + return (uint32_t)(now_ms - link->last_valid_ms) > CANE_WATCHDOG_MS; +} + +void cane_link_outputs(const cane_link_t *link, uint32_t now_ms, cane_outputs_t *out) { + int outage = link_outage(link, now_ms); + out->link_state = outage ? CANE_LINK_OUTAGE : CANE_LINK_HEARTBEAT; + out->link = cane_pulse( + now_ms, + outage ? CANE_LINK_OUT_PERIOD_MS : CANE_LINK_OK_PERIOD_MS, + outage ? CANE_LINK_OUT_ON_MS : CANE_LINK_OK_ON_MS); + if (outage) { + out->hazard = 0; + out->unavailable = 0; + out->route = 0; + return; + } + out->hazard = link->command.hazard == CANE_HAZARD_ELEVATED && + cane_pulse(now_ms, CANE_HAZARD_PERIOD_MS, CANE_HAZARD_ON_MS); + out->unavailable = link->command.system_unavailable && + cane_pulse(now_ms, CANE_UNAVAILABLE_PERIOD_MS, CANE_UNAVAILABLE_ON_MS); + out->route = link->command.route_cue != CANE_ROUTE_NONE && + cane_pulse(now_ms, CANE_ROUTE_PERIOD_MS, CANE_ROUTE_ON_MS); +} + +int cane_status_encode( + const cane_outputs_t *out, + uint32_t last_sequence, + uint8_t bytes[CANE_STATUS_BYTES]) { + bytes[0] = CANE_PACKET_VERSION; + bytes[1] = (uint8_t)out->link_state; + bytes[2] = (uint8_t)((out->hazard ? 1u : 0u) | (out->unavailable ? 2u : 0u) | (out->route ? 4u : 0u) | + (out->link ? 8u : 0u)); + bytes[3] = 0; + write_le32(&bytes[4], last_sequence); + return 1; +} + +int cane_status_decode(const uint8_t *bytes, size_t len, cane_status_t *status) { + if (len != CANE_STATUS_BYTES || bytes[0] != CANE_PACKET_VERSION || bytes[3] != 0) { + return 0; + } + if (bytes[1] != CANE_LINK_HEARTBEAT && bytes[1] != CANE_LINK_OUTAGE) { + return 0; + } + status->link_state = bytes[1]; + status->hazard_on = (bytes[2] & 1u) != 0; + status->unavailable_on = (bytes[2] & 2u) != 0; + status->route_on = (bytes[2] & 4u) != 0; + status->link_on = (bytes[2] & 8u) != 0; + status->last_sequence = read_le32(&bytes[4]); + return 1; +} diff --git a/prototype/firmware/uno_r4_wifi/cane_logic.h b/prototype/firmware/uno_r4_wifi/cane_logic.h new file mode 100644 index 0000000..b8d5518 --- /dev/null +++ b/prototype/firmware/uno_r4_wifi/cane_logic.h @@ -0,0 +1,167 @@ +#ifndef CANE_LOGIC_H +#define CANE_LOGIC_H + +#include +#include + +/* + * Shared claim, packet, and actuator-output logic for the supervised demo. + * Obstacle distance, speed, and time-to-contact are not represented. + * A plane-hit field is optional context and never authorizes a path. + */ + +#define CANE_PACKET_VERSION 1u +#define CANE_PACKET_BYTES 18u +#define CANE_STATUS_BYTES 8u +#define CANE_WATCHDOG_MS 500u +#define CANE_PLANE_CM_NONE 0xFFFFu +#define CANE_PLANE_CM_MAX 2000u + +#define CANE_PIN_HAZARD 2 +#define CANE_PIN_UNAVAILABLE 3 +#define CANE_PIN_ROUTE 4 +#define CANE_PIN_LINK 5 + +#define CANE_HAZARD_PERIOD_MS 200u +#define CANE_HAZARD_ON_MS 100u +#define CANE_UNAVAILABLE_PERIOD_MS 500u +#define CANE_UNAVAILABLE_ON_MS 250u +#define CANE_ROUTE_PERIOD_MS 1000u +#define CANE_ROUTE_ON_MS 200u +#define CANE_LINK_OK_PERIOD_MS 2000u +#define CANE_LINK_OK_ON_MS 80u +#define CANE_LINK_OUT_PERIOD_MS 200u +#define CANE_LINK_OUT_ON_MS 160u + +enum { + CANE_SOURCE_CAMERA = 1, + CANE_SOURCE_SIMULATION = 2 +}; + +enum { + CANE_HAZARD_NO_CLAIM = 0, + CANE_HAZARD_ELEVATED = 1 +}; + +enum { + CANE_ROUTE_NONE = 0, + CANE_ROUTE_DEMO_LEFT = 1, + CANE_ROUTE_DEMO_RIGHT = 2 +}; + +enum { + CANE_TRACKING_UNSUPPORTED = 0, + CANE_TRACKING_UNAVAILABLE = 1, + CANE_TRACKING_LIMITED = 2, + CANE_TRACKING_NORMAL = 3 +}; + +enum { + CANE_LINK_HEARTBEAT = 0, + CANE_LINK_OUTAGE = 1 +}; + +#if defined(__cplusplus) +static_assert(CANE_PACKET_BYTES <= 20, "command packet must fit a 20-byte BLE write"); +static_assert(CANE_STATUS_BYTES <= 20, "status packet must fit a default BLE payload"); +#else +typedef char cane_packet_fits_default_att[(CANE_PACKET_BYTES <= 20) ? 1 : -1]; +typedef char cane_status_fits_default_att[(CANE_STATUS_BYTES <= 20) ? 1 : -1]; +#endif + +typedef struct { + int source; + int tracking; + int camera_authorized; + int world_tracking_supported; + int scene_depth_supported; + int has_plane_hit; + float plane_hit_meters; + int simulation_elevated_hazard; + int simulation_unavailable; + int route_cue; +} cane_input_t; + +typedef struct { + int source; + int hazard; + int system_unavailable; + int route_cue; + int scene_depth_supported; + int plane_hit_valid; + uint16_t plane_hit_cm; + int tracking; +} cane_assessment_t; + +typedef struct { + int source; + int hazard; + int system_unavailable; + int route_cue; + int tracking; + int scene_depth_supported; + uint16_t plane_hit_cm; + uint32_t sequence; + uint16_t time_ms_low; +} cane_command_t; + +typedef struct { + uint32_t last_valid_ms; + int have_valid; + cane_command_t command; +} cane_link_t; + +typedef struct { + int hazard; + int unavailable; + int route; + int link; + int link_state; +} cane_outputs_t; + +typedef struct { + int link_state; + int hazard_on; + int unavailable_on; + int route_on; + int link_on; + uint32_t last_sequence; +} cane_status_t; + +uint16_t cane_crc16(const uint8_t *data, size_t len); + +void cane_assess(const cane_input_t *in, cane_assessment_t *out); + +int cane_camera_displacement_m( + float x0, + float y0, + float z0, + float x1, + float y1, + float z1, + int tracking_normal, + float *meters_out); + +void cane_command_from_assessment( + const cane_assessment_t *assessment, + uint32_t sequence, + uint16_t time_ms_low, + cane_command_t *command); + +int cane_command_admissible(const cane_command_t *command); +int cane_command_encode(const cane_command_t *command, uint8_t out[CANE_PACKET_BYTES]); +int cane_command_decode(const uint8_t *bytes, size_t len, cane_command_t *command); + +void cane_link_init(cane_link_t *link); +int cane_link_accept(cane_link_t *link, const uint8_t *bytes, size_t len, uint32_t now_ms); +void cane_link_outputs(const cane_link_t *link, uint32_t now_ms, cane_outputs_t *out); + +int cane_status_encode( + const cane_outputs_t *out, + uint32_t last_sequence, + uint8_t bytes[CANE_STATUS_BYTES]); +int cane_status_decode(const uint8_t *bytes, size_t len, cane_status_t *status); + +int cane_pulse(uint32_t now_ms, uint32_t period_ms, uint32_t on_ms); + +#endif diff --git a/prototype/firmware/uno_r4_wifi/uno_r4_wifi.ino b/prototype/firmware/uno_r4_wifi/uno_r4_wifi.ino new file mode 100644 index 0000000..4b4e9b6 --- /dev/null +++ b/prototype/firmware/uno_r4_wifi/uno_r4_wifi.ino @@ -0,0 +1,119 @@ +/* + * UNO R4 WiFi peripheral for the supervised cane demo. + * The phone is the BLE central. This board is the peripheral. + * Wi-Fi is not started. Arduino documents that the ESP32-S3 antenna + * is shared, so this sketch uses Bluetooth LE only. + * + * D2-D5 are 5 V logic enables for external actuator drivers. + * The UNO R4 WiFi datasheet says each RA4M1 GPIO can safely handle + * up to 8 mA. Do not connect a motor, solenoid, or vibration puck + * directly to a GPIO. See docs/PROTOTYPE.md. + */ + +#include + +#include "cane_logic.h" + +static BLEService caneService("8f3a1c20-7b6e-4d5a-9c11-6e2f0a9b1001"); +static BLECharacteristic commandCharacteristic( + "8f3a1c20-7b6e-4d5a-9c11-6e2f0a9b1002", + BLEWrite | BLEWriteWithoutResponse, + CANE_PACKET_BYTES); +static BLECharacteristic statusCharacteristic( + "8f3a1c20-7b6e-4d5a-9c11-6e2f0a9b1003", + BLERead | BLENotify, + CANE_STATUS_BYTES); + +static cane_link_t link; +static cane_outputs_t previous; +static int have_previous = 0; +static int ble_ready = 0; +static uint32_t last_status_ms = 0; + +static void set_pin_low(int pin) { + pinMode(pin, OUTPUT); + digitalWrite(pin, LOW); +} + +static void print_outputs(uint32_t now_ms, const cane_outputs_t *out) { + Serial.print("ms="); + Serial.print(now_ms); + Serial.print(" link="); + Serial.print(out->link_state == CANE_LINK_OUTAGE ? "outage" : "heartbeat"); + Serial.print(" pins hazard="); + Serial.print(out->hazard); + Serial.print(" unavailable="); + Serial.print(out->unavailable); + Serial.print(" route="); + Serial.print(out->route); + Serial.print(" linkpin="); + Serial.println(out->link); +} + +static void apply_outputs(uint32_t now_ms) { + cane_outputs_t out; + cane_link_outputs(&link, now_ms, &out); + digitalWrite(CANE_PIN_HAZARD, out.hazard ? HIGH : LOW); + digitalWrite(CANE_PIN_UNAVAILABLE, out.unavailable ? HIGH : LOW); + digitalWrite(CANE_PIN_ROUTE, out.route ? HIGH : LOW); + digitalWrite(CANE_PIN_LINK, out.link ? HIGH : LOW); + if (!have_previous || out.hazard != previous.hazard || out.unavailable != previous.unavailable || + out.route != previous.route || out.link_state != previous.link_state) { + print_outputs(now_ms, &out); + previous = out; + have_previous = 1; + } + if ((uint32_t)(now_ms - last_status_ms) >= 200u) { + uint8_t status[CANE_STATUS_BYTES]; + uint32_t sequence = link.have_valid ? link.command.sequence : 0u; + cane_status_encode(&out, sequence, status); + statusCharacteristic.writeValue(status, CANE_STATUS_BYTES); + last_status_ms = now_ms; + } +} + +void setup() { + set_pin_low(CANE_PIN_HAZARD); + set_pin_low(CANE_PIN_UNAVAILABLE); + set_pin_low(CANE_PIN_ROUTE); + set_pin_low(CANE_PIN_LINK); + cane_link_init(&link); + Serial.begin(115200); + Serial.println("Cane demo controller"); + Serial.println("Logic outputs only: D2 hazard, D3 unavailable, D4 route demo, D5 link."); + Serial.println("No packet yet, so the link output uses the outage pattern."); + + if (!BLE.begin()) { + Serial.println("BLE.begin failed. Actuator enables stay in the link-outage pattern."); + return; + } + BLE.setLocalName("CaneDemo"); + BLE.setAdvertisedService(caneService); + caneService.addCharacteristic(commandCharacteristic); + caneService.addCharacteristic(statusCharacteristic); + BLE.addService(caneService); + BLE.advertise(); + ble_ready = 1; + Serial.println("Advertising CaneDemo as a BLE peripheral."); +} + +void loop() { + uint32_t now_ms = millis(); + if (ble_ready) { + BLE.poll(); + if (commandCharacteristic.written()) { + const uint8_t *incoming = commandCharacteristic.value(); + int length = commandCharacteristic.valueLength(); + int accepted = 0; + if (incoming != nullptr && length > 0) { + accepted = cane_link_accept(&link, incoming, (size_t)length, now_ms); + } + if (!accepted) { + Serial.print("ms="); + Serial.print(now_ms); + Serial.println(" rejected packet"); + } + } + } + apply_outputs(now_ms); +} diff --git a/prototype/ios/CaneDemo/CaneDemo.xcodeproj/project.pbxproj b/prototype/ios/CaneDemo/CaneDemo.xcodeproj/project.pbxproj new file mode 100644 index 0000000..a667355 --- /dev/null +++ b/prototype/ios/CaneDemo/CaneDemo.xcodeproj/project.pbxproj @@ -0,0 +1,280 @@ +// !$*UTF8*$! +{ + archiveVersion = 1; + classes = { + }; + objectVersion = 56; + objects = { + +/* Begin PBXBuildFile section */ + B10000000000000000000001 /* CaneDemoApp.swift in Sources */ = {isa = PBXBuildFile; fileRef = F10000000000000000000001 /* CaneDemoApp.swift */; }; + B10000000000000000000002 /* DemoController.swift in Sources */ = {isa = PBXBuildFile; fileRef = F10000000000000000000002 /* DemoController.swift */; }; + B10000000000000000000003 /* DebugRootView.swift in Sources */ = {isa = PBXBuildFile; fileRef = F10000000000000000000003 /* DebugRootView.swift */; }; + B10000000000000000000004 /* cane_logic.c in Sources */ = {isa = PBXBuildFile; fileRef = F10000000000000000000004 /* cane_logic.c */; }; + B10000000000000000000005 /* ARKit.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = F10000000000000000000008 /* ARKit.framework */; }; + B10000000000000000000006 /* CoreBluetooth.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = F10000000000000000000009 /* CoreBluetooth.framework */; }; +/* End PBXBuildFile section */ + +/* Begin PBXFileReference section */ + F10000000000000000000001 /* CaneDemoApp.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CaneDemoApp.swift; sourceTree = ""; }; + F10000000000000000000002 /* DemoController.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = DemoController.swift; sourceTree = ""; }; + F10000000000000000000003 /* DebugRootView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = DebugRootView.swift; sourceTree = ""; }; + F10000000000000000000004 /* cane_logic.c */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.c; name = cane_logic.c; path = ../../firmware/uno_r4_wifi/cane_logic.c; sourceTree = ""; }; + F10000000000000000000005 /* cane_logic.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; name = cane_logic.h; path = ../../firmware/uno_r4_wifi/cane_logic.h; sourceTree = ""; }; + F10000000000000000000006 /* Info.plist */ = {isa = PBXFileReference; lastKnownFileType = text.plist.xml; path = Info.plist; sourceTree = ""; }; + F10000000000000000000007 /* CaneDemo-Bridging-Header.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = "CaneDemo-Bridging-Header.h"; sourceTree = ""; }; + F10000000000000000000008 /* ARKit.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = ARKit.framework; path = System/Library/Frameworks/ARKit.framework; sourceTree = SDKROOT; }; + F10000000000000000000009 /* CoreBluetooth.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = CoreBluetooth.framework; path = System/Library/Frameworks/CoreBluetooth.framework; sourceTree = SDKROOT; }; + F1000000000000000000000A /* CaneDemo.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = CaneDemo.app; sourceTree = BUILT_PRODUCTS_DIR; }; +/* End PBXFileReference section */ + +/* Begin PBXFrameworksBuildPhase section */ + A10000000000000000000004 /* Frameworks */ = { + isa = PBXFrameworksBuildPhase; + buildActionMask = 2147483647; + files = ( + B10000000000000000000005 /* ARKit.framework in Frameworks */, + B10000000000000000000006 /* CoreBluetooth.framework in Frameworks */, + ); + runOnlyForDeploymentPostprocessing = 0; + }; +/* End PBXFrameworksBuildPhase section */ + +/* Begin PBXGroup section */ + A10000000000000000000007 /* Main */ = { + isa = PBXGroup; + children = ( + A10000000000000000000008 /* CaneDemo */, + F10000000000000000000004 /* cane_logic.c */, + F10000000000000000000005 /* cane_logic.h */, + A10000000000000000000009 /* Frameworks */, + A1000000000000000000000A /* Products */, + ); + sourceTree = ""; + }; + A10000000000000000000008 /* CaneDemo */ = { + isa = PBXGroup; + children = ( + F10000000000000000000001 /* CaneDemoApp.swift */, + F10000000000000000000002 /* DemoController.swift */, + F10000000000000000000003 /* DebugRootView.swift */, + F10000000000000000000007 /* CaneDemo-Bridging-Header.h */, + F10000000000000000000006 /* Info.plist */, + ); + path = CaneDemo; + sourceTree = ""; + }; + A10000000000000000000009 /* Frameworks */ = { + isa = PBXGroup; + children = ( + F10000000000000000000008 /* ARKit.framework */, + F10000000000000000000009 /* CoreBluetooth.framework */, + ); + name = Frameworks; + sourceTree = ""; + }; + A1000000000000000000000A /* Products */ = { + isa = PBXGroup; + children = ( + F1000000000000000000000A /* CaneDemo.app */, + ); + name = Products; + sourceTree = ""; + }; +/* End PBXGroup section */ + +/* Begin PBXNativeTarget section */ + A10000000000000000000002 /* CaneDemo */ = { + isa = PBXNativeTarget; + buildConfigurationList = A1000000000000000000000C /* Build configuration list for PBXNativeTarget "CaneDemo" */; + buildPhases = ( + A10000000000000000000003 /* Sources */, + A10000000000000000000004 /* Frameworks */, + ); + buildRules = ( + ); + dependencies = ( + ); + name = CaneDemo; + productName = CaneDemo; + productReference = F1000000000000000000000A /* CaneDemo.app */; + productType = "com.apple.product-type.application"; + }; +/* End PBXNativeTarget section */ + +/* Begin PBXProject section */ + A10000000000000000000001 /* Project object */ = { + isa = PBXProject; + attributes = { + BuildIndependentTargetsInParallel = 1; + LastUpgradeCheck = 1600; + TargetAttributes = { + A10000000000000000000002 = { + CreatedOnToolsVersion = 16.0; + }; + }; + }; + buildConfigurationList = A1000000000000000000000B /* Build configuration list for PBXProject "CaneDemo" */; + compatibilityVersion = "Xcode 14.0"; + developmentRegion = en; + hasScannedForEncodings = 0; + knownRegions = ( + en, + Base, + ); + mainGroup = A10000000000000000000007; + productRefGroup = A1000000000000000000000A /* Products */; + projectDirPath = ""; + projectRoot = ""; + targets = ( + A10000000000000000000002 /* CaneDemo */, + ); + }; +/* End PBXProject section */ + +/* Begin PBXSourcesBuildPhase section */ + A10000000000000000000003 /* Sources */ = { + isa = PBXSourcesBuildPhase; + buildActionMask = 2147483647; + files = ( + B10000000000000000000001 /* CaneDemoApp.swift in Sources */, + B10000000000000000000002 /* DemoController.swift in Sources */, + B10000000000000000000003 /* DebugRootView.swift in Sources */, + B10000000000000000000004 /* cane_logic.c in Sources */, + ); + runOnlyForDeploymentPostprocessing = 0; + }; +/* End PBXSourcesBuildPhase section */ + +/* Begin XCBuildConfiguration section */ + A1000000000000000000000D /* Debug */ = { + isa = XCBuildConfiguration; + buildSettings = { + ALWAYS_SEARCH_USER_PATHS = NO; + CLANG_ENABLE_MODULES = YES; + CLANG_ENABLE_OBJC_ARC = YES; + COPY_PHASE_STRIP = NO; + DEBUG_INFORMATION_FORMAT = dwarf; + ENABLE_STRICT_OBJC_MSGSEND = YES; + GCC_C_LANGUAGE_STANDARD = c11; + GCC_DYNAMIC_NO_PIC = NO; + GCC_OPTIMIZATION_LEVEL = 0; + IPHONEOS_DEPLOYMENT_TARGET = 18.0; + MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE; + ONLY_ACTIVE_ARCH = YES; + SDKROOT = iphoneos; + SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG; + SWIFT_OPTIMIZATION_LEVEL = "-Onone"; + }; + name = Debug; + }; + A1000000000000000000000E /* Release */ = { + isa = XCBuildConfiguration; + buildSettings = { + ALWAYS_SEARCH_USER_PATHS = NO; + CLANG_ENABLE_MODULES = YES; + CLANG_ENABLE_OBJC_ARC = YES; + COPY_PHASE_STRIP = NO; + DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym"; + ENABLE_NS_ASSERTIONS = NO; + ENABLE_STRICT_OBJC_MSGSEND = YES; + GCC_C_LANGUAGE_STANDARD = c11; + IPHONEOS_DEPLOYMENT_TARGET = 18.0; + MTL_ENABLE_DEBUG_INFO = NO; + SDKROOT = iphoneos; + SWIFT_COMPILATION_MODE = wholemodule; + VALIDATE_PRODUCT = YES; + }; + name = Release; + }; + A1000000000000000000000F /* Debug */ = { + isa = XCBuildConfiguration; + buildSettings = { + ASSETCATALOG_COMPILER_APPICON_NAME = ""; + CODE_SIGN_STYLE = Automatic; + CURRENT_PROJECT_VERSION = 1; + DEVELOPMENT_TEAM = ""; + ENABLE_USER_SCRIPT_SANDBOXING = YES; + GENERATE_INFOPLIST_FILE = NO; + HEADER_SEARCH_PATHS = ( + "$(inherited)", + "$(PROJECT_DIR)/../../firmware/uno_r4_wifi", + ); + INFOPLIST_FILE = CaneDemo/Info.plist; + INFOPLIST_KEY_UILaunchScreen_Generation = NO; + IPHONEOS_DEPLOYMENT_TARGET = 18.0; + LD_RUNPATH_SEARCH_PATHS = ( + "$(inherited)", + "@executable_path/Frameworks", + ); + MARKETING_VERSION = 0.1.0; + PRODUCT_BUNDLE_IDENTIFIER = com.makeuc2026.canedemo; + PRODUCT_NAME = "$(TARGET_NAME)"; + SDKROOT = iphoneos; + SUPPORTED_PLATFORMS = "iphoneos iphonesimulator"; + SUPPORTS_MACCATALYST = NO; + SWIFT_EMIT_LOC_STRINGS = YES; + SWIFT_OBJC_BRIDGING_HEADER = "CaneDemo/CaneDemo-Bridging-Header.h"; + SWIFT_VERSION = 5.0; + TARGETED_DEVICE_FAMILY = 1; + }; + name = Debug; + }; + A10000000000000000000010 /* Release */ = { + isa = XCBuildConfiguration; + buildSettings = { + ASSETCATALOG_COMPILER_APPICON_NAME = ""; + CODE_SIGN_STYLE = Automatic; + CURRENT_PROJECT_VERSION = 1; + DEVELOPMENT_TEAM = ""; + ENABLE_USER_SCRIPT_SANDBOXING = YES; + GENERATE_INFOPLIST_FILE = NO; + HEADER_SEARCH_PATHS = ( + "$(inherited)", + "$(PROJECT_DIR)/../../firmware/uno_r4_wifi", + ); + INFOPLIST_FILE = CaneDemo/Info.plist; + INFOPLIST_KEY_UILaunchScreen_Generation = NO; + IPHONEOS_DEPLOYMENT_TARGET = 18.0; + LD_RUNPATH_SEARCH_PATHS = ( + "$(inherited)", + "@executable_path/Frameworks", + ); + MARKETING_VERSION = 0.1.0; + PRODUCT_BUNDLE_IDENTIFIER = com.makeuc2026.canedemo; + PRODUCT_NAME = "$(TARGET_NAME)"; + SDKROOT = iphoneos; + SUPPORTED_PLATFORMS = "iphoneos iphonesimulator"; + SUPPORTS_MACCATALYST = NO; + SWIFT_EMIT_LOC_STRINGS = YES; + SWIFT_OBJC_BRIDGING_HEADER = "CaneDemo/CaneDemo-Bridging-Header.h"; + SWIFT_VERSION = 5.0; + TARGETED_DEVICE_FAMILY = 1; + }; + name = Release; + }; +/* End XCBuildConfiguration section */ + +/* Begin XCConfigurationList section */ + A1000000000000000000000B /* Build configuration list for PBXProject "CaneDemo" */ = { + isa = XCConfigurationList; + buildConfigurations = ( + A1000000000000000000000D /* Debug */, + A1000000000000000000000E /* Release */, + ); + defaultConfigurationIsVisible = 0; + defaultConfigurationName = Release; + }; + A1000000000000000000000C /* Build configuration list for PBXNativeTarget "CaneDemo" */ = { + isa = XCConfigurationList; + buildConfigurations = ( + A1000000000000000000000F /* Debug */, + A10000000000000000000010 /* Release */, + ); + defaultConfigurationIsVisible = 0; + defaultConfigurationName = Release; + }; +/* End XCConfigurationList section */ + }; + rootObject = A10000000000000000000001 /* Project object */; +} diff --git a/prototype/ios/CaneDemo/CaneDemo.xcodeproj/xcshareddata/xcschemes/CaneDemo.xcscheme b/prototype/ios/CaneDemo/CaneDemo.xcodeproj/xcshareddata/xcschemes/CaneDemo.xcscheme new file mode 100644 index 0000000..4ecd0ae --- /dev/null +++ b/prototype/ios/CaneDemo/CaneDemo.xcodeproj/xcshareddata/xcschemes/CaneDemo.xcscheme @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/prototype/ios/CaneDemo/CaneDemo/CaneDemo-Bridging-Header.h b/prototype/ios/CaneDemo/CaneDemo/CaneDemo-Bridging-Header.h new file mode 100644 index 0000000..1123757 --- /dev/null +++ b/prototype/ios/CaneDemo/CaneDemo/CaneDemo-Bridging-Header.h @@ -0,0 +1 @@ +#include "cane_logic.h" diff --git a/prototype/ios/CaneDemo/CaneDemo/CaneDemoApp.swift b/prototype/ios/CaneDemo/CaneDemo/CaneDemoApp.swift new file mode 100644 index 0000000..c355c6c --- /dev/null +++ b/prototype/ios/CaneDemo/CaneDemo/CaneDemoApp.swift @@ -0,0 +1,12 @@ +import SwiftUI + +@main +struct CaneDemoApp: App { + @StateObject private var demo = DemoController() + + var body: some Scene { + WindowGroup { + DebugRootView(demo: demo) + } + } +} diff --git a/prototype/ios/CaneDemo/CaneDemo/DebugRootView.swift b/prototype/ios/CaneDemo/CaneDemo/DebugRootView.swift new file mode 100644 index 0000000..084006a --- /dev/null +++ b/prototype/ios/CaneDemo/CaneDemo/DebugRootView.swift @@ -0,0 +1,138 @@ +import ARKit +import SceneKit +import SwiftUI + +struct DebugRootView: View { + @ObservedObject var demo: DemoController + + var body: some View { + ScrollView { + VStack(alignment: .leading, spacing: 16) { + Text("Supervised cane demo") + .font(.largeTitle) + .accessibilityAddTraits(.isHeader) + Text("Not a mobility aid. The existing cane stays in use. No claim here means the way is clear. A quiet hazard channel is not an all-clear.") + .font(.body) + CameraPreview(session: demo.session) + .frame(height: 220) + .accessibilityLabel("Rear camera preview") + sourceSection + cameraSection + claimSection + if demo.sourceIsSimulation { + simulationSection + } + linkSection + } + .padding() + .frame(maxWidth: .infinity, alignment: .leading) + } + .onAppear { demo.prepare() } + } + + private var sourceSection: some View { + VStack(alignment: .leading, spacing: 8) { + Text("Outgoing source") + .font(.title2) + Picker("Outgoing source", selection: Binding( + get: { demo.sourceIsSimulation }, + set: { demo.setSource(simulation: $0) } + )) { + Text("Camera pipeline").tag(false) + Text("Simulation").tag(true) + } + .pickerStyle(.segmented) + if demo.sourceIsSimulation { + Text("SIMULATED INPUT. These claims are not from the camera.") + .font(.headline) + .accessibilityAddTraits(.isHeader) + } + } + } + + private var cameraSection: some View { + VStack(alignment: .leading, spacing: 8) { + Text("Camera readout") + .font(.title2) + labeled("World tracking supported", demo.worldTrackingSupported ? "Yes" : "No") + labeled("sceneDepth supported", demo.sceneDepthSupported ? "Yes, but this build does not enable it" : "No") + labeled("Camera permission", demo.cameraAuthorized ? "Authorized" : "Not authorized") + labeled("Tracking", demo.trackingText) + labeled("Device motion", demo.displacementText) + Text("The step above is ARKit camera travel between consecutive normal frames. It is not an obstacle distance and it is not a speed.") + .font(.footnote) + labeled("Frame interval", demo.frameIntervalText) + labeled("Plane context", demo.planeText) + Text("A plane hit is the distance from the ARKit camera pose to an existing detected plane. It is not a clearance and it does not raise a hazard.") + .font(.footnote) + } + } + + private var claimSection: some View { + VStack(alignment: .leading, spacing: 8) { + Text("Outgoing claim") + .font(.title2) + Text(demo.claimText) + .font(.title3) + Text(demo.sendText) + } + } + + private var simulationSection: some View { + VStack(alignment: .leading, spacing: 8) { + Text("Simulation controls") + .font(.title2) + Toggle("Simulated elevated hazard", isOn: $demo.simulatedHazard) + Toggle("Simulated system unavailable", isOn: $demo.simulatedUnavailable) + Picker("Demo route label", selection: $demo.simulatedRoute) { + Text("None").tag(CANE_ROUTE_NONE) + Text("Left label").tag(CANE_ROUTE_DEMO_LEFT) + Text("Right label").tag(CANE_ROUTE_DEMO_RIGHT) + } + Text("A left or right label only marks a manual demo cue on the route channel. It is not a direction that avoids a collision.") + .font(.footnote) + } + .onChange(of: demo.simulatedHazard) { _, _ in demo.refreshClaim() } + .onChange(of: demo.simulatedUnavailable) { _, _ in demo.refreshClaim() } + .onChange(of: demo.simulatedRoute) { _, _ in demo.refreshClaim() } + } + + private var linkSection: some View { + VStack(alignment: .leading, spacing: 8) { + Text("Controller link") + .font(.title2) + labeled("Phone", demo.bluetoothText) + labeled("Board status", demo.boardText) + Text("The board, not the phone, decides link outage. Until a status notification arrives, board output is unknown. The phone sends a packet about ten times a second while connected. That interval is the send timer, not a measured end-to-end latency.") + .font(.footnote) + } + } + + private func labeled(_ title: String, _ value: String) -> some View { + VStack(alignment: .leading, spacing: 2) { + Text(title) + .font(.headline) + Text(value) + .font(.body) + } + .accessibilityElement(children: .combine) + } +} + +struct CameraPreview: UIViewRepresentable { + let session: ARSession + + func makeUIView(context: Context) -> ARSCNView { + let view = ARSCNView(frame: .zero) + view.session = session + view.automaticallyUpdatesLighting = false + view.scene = SCNScene() + return view + } + + func updateUIView(_ uiView: ARSCNView, context: Context) { + if uiView.session !== session { + uiView.session = session + } + } +} diff --git a/prototype/ios/CaneDemo/CaneDemo/DemoController.swift b/prototype/ios/CaneDemo/CaneDemo/DemoController.swift new file mode 100644 index 0000000..0d15684 --- /dev/null +++ b/prototype/ios/CaneDemo/CaneDemo/DemoController.swift @@ -0,0 +1,360 @@ +import ARKit +import AVFoundation +import CoreBluetooth +import Foundation +import simd +import UIKit + +final class DemoController: NSObject, ObservableObject, ARSessionDelegate, CBCentralManagerDelegate, CBPeripheralDelegate { + let session = ARSession() + + @Published var sourceIsSimulation = false + @Published var simulatedHazard = false + @Published var simulatedUnavailable = false + @Published var simulatedRoute = CANE_ROUTE_NONE + + @Published var cameraAuthorized = false + @Published var worldTrackingSupported = false + @Published var sceneDepthSupported = false + @Published var trackingText = "Not started" + @Published var displacementText = "Unknown" + @Published var frameIntervalText = "Unknown" + @Published var planeText = "No existing-plane hit" + @Published var claimText = "No packet yet" + @Published var sendText = "Not sending" + @Published var bluetoothText = "Bluetooth starting" + @Published var boardText = "No controller status received" + + private var hasPlaneHit = false + private var planeHitMeters: Float = 0 + private var tracking = CANE_TRACKING_UNSUPPORTED + private var previousNormalPosition: SIMD3? + private var previousTimestamp: TimeInterval? + private var sequence: UInt32 = 0 + private var latestPacket: Data? + private var timer: Timer? + + private var central: CBCentralManager! + private var peripheral: CBPeripheral? + private var commandCharacteristic: CBCharacteristic? + private var statusCharacteristic: CBCharacteristic? + + private let serviceUUID = CBUUID(string: "8f3a1c20-7b6e-4d5a-9c11-6e2f0a9b1001") + private let commandUUID = CBUUID(string: "8f3a1c20-7b6e-4d5a-9c11-6e2f0a9b1002") + private let statusUUID = CBUUID(string: "8f3a1c20-7b6e-4d5a-9c11-6e2f0a9b1003") + + override init() { + super.init() + session.delegate = self + central = CBCentralManager(delegate: self, queue: nil) + timer = Timer.scheduledTimer(withTimeInterval: 0.1, repeats: true) { [weak self] _ in + self?.sendLatest() + } + } + + func prepare() { + worldTrackingSupported = ARWorldTrackingConfiguration.isSupported + sceneDepthSupported = ARWorldTrackingConfiguration.supportsFrameSemantics(.sceneDepth) + switch AVCaptureDevice.authorizationStatus(for: .video) { + case .authorized: + cameraAuthorized = true + startSession() + case .notDetermined: + AVCaptureDevice.requestAccess(for: .video) { [weak self] granted in + DispatchQueue.main.async { + self?.cameraAuthorized = granted + if granted { + self?.startSession() + } else { + self?.refreshClaim() + } + } + } + default: + cameraAuthorized = false + refreshClaim() + } + } + + func startSession() { + guard worldTrackingSupported else { + tracking = CANE_TRACKING_UNSUPPORTED + trackingText = "World tracking is not supported on this device" + refreshClaim() + return + } + let configuration = ARWorldTrackingConfiguration() + configuration.worldAlignment = .gravity + configuration.planeDetection = [.horizontal, .vertical] + configuration.frameSemantics = [] + session.run(configuration, options: [.resetTracking, .removeExistingAnchors]) + trackingText = "AR session started. sceneDepth is not enabled." + refreshClaim() + } + + func setSource(simulation: Bool) { + sourceIsSimulation = simulation + if !simulation { + simulatedHazard = false + simulatedUnavailable = false + simulatedRoute = CANE_ROUTE_NONE + } + refreshClaim() + } + + func refreshClaim() { + let input = currentInput() + var mutable = input + var assessment = cane_assessment_t() + cane_assess(&mutable, &assessment) + var command = cane_command_t() + sequence &+= 1 + let stamp = UInt16(truncatingIfNeeded: UInt64(Date().timeIntervalSince1970 * 1000)) + cane_command_from_assessment(&assessment, sequence, stamp, &command) + var packet = [UInt8](repeating: 0, count: Int(CANE_PACKET_BYTES)) + if cane_command_encode(&command, &packet) == 1 { + latestPacket = Data(packet) + claimText = describe(assessment) + sendText = "Packet \(sequence) ready" + } else { + latestPacket = nil + claimText = describe(assessment) + sendText = "Shared checker refused the packet" + } + } + + private func currentInput() -> cane_input_t { + var input = cane_input_t( + source: sourceIsSimulation ? CANE_SOURCE_SIMULATION : CANE_SOURCE_CAMERA, + tracking: tracking, + camera_authorized: Int32(cameraAuthorized ? 1 : 0), + world_tracking_supported: Int32(worldTrackingSupported ? 1 : 0), + scene_depth_supported: Int32(sceneDepthSupported ? 1 : 0), + has_plane_hit: 0, + plane_hit_meters: 0, + simulation_elevated_hazard: 0, + simulation_unavailable: 0, + route_cue: CANE_ROUTE_NONE + ) + if sourceIsSimulation { + input.simulation_elevated_hazard = Int32(simulatedHazard ? 1 : 0) + input.simulation_unavailable = Int32(simulatedUnavailable ? 1 : 0) + input.route_cue = simulatedRoute + } else { + input.has_plane_hit = Int32(hasPlaneHit ? 1 : 0) + input.plane_hit_meters = planeHitMeters + } + return input + } + + private func describe(_ assessment: cane_assessment_t) -> String { + let source = assessment.source == CANE_SOURCE_SIMULATION ? "Simulation" : "Camera pipeline" + let hazard = assessment.hazard == CANE_HAZARD_ELEVATED ? "Elevated hazard claim" : "No hazard claim" + let availability = assessment.system_unavailable == 1 ? "System unavailable" : "Pipeline running" + let route: String + switch assessment.route_cue { + case CANE_ROUTE_DEMO_LEFT: + route = "Demo route cue: left label" + case CANE_ROUTE_DEMO_RIGHT: + route = "Demo route cue: right label" + default: + route = "No route cue" + } + return "\(source). \(hazard). \(availability). \(route). This is not an all-clear." + } + + private func sendLatest() { + guard let latestPacket, let peripheral, let commandCharacteristic else { + return + } + guard peripheral.state == .connected else { + return + } + let writeType: CBCharacteristicWriteType = commandCharacteristic.properties.contains(.writeWithoutResponse) + ? .withoutResponse + : .withResponse + peripheral.writeValue(latestPacket, for: commandCharacteristic, type: writeType) + sendText = "Last write attempted for sequence \(sequence)" + } + + func session(_ session: ARSession, didUpdate frame: ARFrame) { + let state = frame.camera.trackingState + let code: Int32 + let label: String + switch state { + case .normal: + code = CANE_TRACKING_NORMAL + label = "Tracking normal" + case .limited(let reason): + code = CANE_TRACKING_LIMITED + label = "Tracking limited (\(reasonText(reason)))" + case .notAvailable: + code = CANE_TRACKING_UNAVAILABLE + label = "Tracking not available" + } + let position = SIMD3( + frame.camera.transform.columns.3.x, + frame.camera.transform.columns.3.y, + frame.camera.transform.columns.3.z + ) + var displacement: String = "Unknown" + if code == CANE_TRACKING_NORMAL, let previous = previousNormalPosition { + var meters: Float = 0 + let ok = cane_camera_displacement_m( + previous.x, previous.y, previous.z, + position.x, position.y, position.z, + 1, + &meters + ) + if ok == 1 { + displacement = String(format: "ARKit camera step %.3f m since the previous normal frame", meters) + } + } + if code == CANE_TRACKING_NORMAL { + previousNormalPosition = position + } else { + previousNormalPosition = nil + } + var interval = "Unknown" + if let previousTimestamp { + let delta = frame.timestamp - previousTimestamp + if delta > 0 { + interval = String(format: "ARKit frame interval %.3f s", delta) + } + } + previousTimestamp = frame.timestamp + + var planeValid = false + var planeMeters: Float = 0 + var planeLabel = "No existing-plane hit" + if let query = frame.raycastQuery(from: CGPoint(x: 0.5, y: 0.5), allowing: .existingPlaneGeometry, alignment: .any) { + if let hit = session.raycast(query).first { + let hitPosition = SIMD3( + hit.worldTransform.columns.3.x, + hit.worldTransform.columns.3.y, + hit.worldTransform.columns.3.z + ) + let step = simd_distance(position, hitPosition) + planeValid = true + planeMeters = step + planeLabel = String(format: "Existing-plane hit %.2f m from the camera pose. Not obstacle clearance.", step) + } + } + + DispatchQueue.main.async { [weak self] in + guard let self else { return } + self.tracking = code + self.trackingText = label + self.displacementText = displacement + self.frameIntervalText = interval + self.hasPlaneHit = planeValid + self.planeHitMeters = planeMeters + self.planeText = planeLabel + self.refreshClaim() + } + } + + func session(_ session: ARSession, didFailWithError error: Error) { + DispatchQueue.main.async { [weak self] in + self?.tracking = CANE_TRACKING_UNAVAILABLE + self?.trackingText = "AR session failed: \(error.localizedDescription)" + self?.previousNormalPosition = nil + self?.refreshClaim() + } + } + + func centralManagerDidUpdateState(_ central: CBCentralManager) { + switch central.state { + case .poweredOn: + bluetoothText = "Scanning for CaneDemo" + central.scanForPeripherals(withServices: [serviceUUID], options: nil) + case .poweredOff: + bluetoothText = "Bluetooth is off" + case .unauthorized: + bluetoothText = "Bluetooth permission denied" + case .unsupported: + bluetoothText = "Bluetooth LE is not supported" + default: + bluetoothText = "Bluetooth state \(central.state.rawValue)" + } + } + + func centralManager(_ central: CBCentralManager, didDiscover peripheral: CBPeripheral, advertisementData: [String: Any], rssi RSSI: NSNumber) { + self.peripheral = peripheral + peripheral.delegate = self + central.stopScan() + bluetoothText = "Connecting to \(peripheral.name ?? "cane controller")" + central.connect(peripheral, options: nil) + } + + func centralManager(_ central: CBCentralManager, didConnect peripheral: CBPeripheral) { + bluetoothText = "Connected. Discovering service." + peripheral.discoverServices([serviceUUID]) + } + + func centralManager(_ central: CBCentralManager, didDisconnectPeripheral peripheral: CBPeripheral, error: Error?) { + commandCharacteristic = nil + statusCharacteristic = nil + boardText = "Controller disconnected. The board watchdog should enter link outage." + bluetoothText = "Disconnected. Scanning again." + central.scanForPeripherals(withServices: [serviceUUID], options: nil) + } + + func peripheral(_ peripheral: CBPeripheral, didDiscoverServices error: Error?) { + if let error { + bluetoothText = "Service discovery failed: \(error.localizedDescription)" + return + } + guard let service = peripheral.services?.first(where: { $0.uuid == serviceUUID }) else { + bluetoothText = "Cane service missing" + return + } + peripheral.discoverCharacteristics([commandUUID, statusUUID], for: service) + } + + func peripheral(_ peripheral: CBPeripheral, didDiscoverCharacteristicsFor service: CBService, error: Error?) { + if let error { + bluetoothText = "Characteristic discovery failed: \(error.localizedDescription)" + return + } + commandCharacteristic = service.characteristics?.first(where: { $0.uuid == commandUUID }) + statusCharacteristic = service.characteristics?.first(where: { $0.uuid == statusUUID }) + if let statusCharacteristic { + peripheral.setNotifyValue(true, for: statusCharacteristic) + } + bluetoothText = commandCharacteristic == nil ? "Command characteristic missing" : "Link ready for packets" + } + + func peripheral(_ peripheral: CBPeripheral, didUpdateValueFor characteristic: CBCharacteristic, error: Error?) { + guard error == nil, characteristic.uuid == statusUUID, let value = characteristic.value else { + return + } + let bytes = [UInt8](value) + var status = cane_status_t() + let decoded = bytes.withUnsafeBufferPointer { buffer -> Int32 in + guard let base = buffer.baseAddress else { return 0 } + return cane_status_decode(base, buffer.count, &status) + } + guard decoded == 1 else { + boardText = "Controller status failed the shared decoder" + return + } + let link = status.link_state == CANE_LINK_OUTAGE ? "link outage" : "link heartbeat" + boardText = "\(link). sequence \(status.last_sequence). pins hazard \(status.hazard_on) unavailable \(status.unavailable_on) route \(status.route_on) link \(status.link_on)" + } + + private func reasonText(_ reason: ARCamera.TrackingState.Reason) -> String { + switch reason { + case .initializing: + return "initializing" + case .excessiveMotion: + return "excessive motion" + case .insufficientFeatures: + return "insufficient features" + case .relocalizing: + return "relocalizing" + @unknown default: + return "unspecified" + } + } +} diff --git a/prototype/ios/CaneDemo/CaneDemo/Info.plist b/prototype/ios/CaneDemo/CaneDemo/Info.plist new file mode 100644 index 0000000..d9e9a02 --- /dev/null +++ b/prototype/ios/CaneDemo/CaneDemo/Info.plist @@ -0,0 +1,51 @@ + + + + + CFBundleDevelopmentRegion + en + CFBundleDisplayName + Cane Demo + CFBundleExecutable + $(EXECUTABLE_NAME) + CFBundleIdentifier + $(PRODUCT_BUNDLE_IDENTIFIER) + CFBundleInfoDictionaryVersion + 6.0 + CFBundleName + $(PRODUCT_NAME) + CFBundlePackageType + APPL + CFBundleShortVersionString + $(MARKETING_VERSION) + CFBundleVersion + $(CURRENT_PROJECT_VERSION) + LSRequiresIPhoneOS + + NSBluetoothAlwaysUsageDescription + The supervised demo connects as a Bluetooth central to the cane controller to send claim packets and read controller status. + NSCameraUsageDescription + The supervised demo uses the rear camera for ARKit tracking and the debug preview. The camera image is not converted into an obstacle distance. + NSMotionUsageDescription + ARKit uses motion sensors for visual-inertial camera tracking. Motion is not turned into an obstacle speed. + UIApplicationSceneManifest + + UIApplicationSupportsMultipleScenes + + + UILaunchScreen + + UIRequiredDeviceCapabilities + + arm64 + arkit + bluetooth-le + + UISupportedInterfaceOrientations + + UIInterfaceOrientationPortrait + UIInterfaceOrientationLandscapeLeft + UIInterfaceOrientationLandscapeRight + + + diff --git a/prototype/tests/test_cane.c b/prototype/tests/test_cane.c new file mode 100644 index 0000000..f480cfa --- /dev/null +++ b/prototype/tests/test_cane.c @@ -0,0 +1,297 @@ +#include "cane_logic.h" + +#include +#include +#include + +static int failures = 0; + +static void expect(int condition, const char *message) { + if (!condition) { + fprintf(stderr, "FAIL %s\n", message); + failures++; + } +} + +static cane_input_t camera_ready(void) { + cane_input_t input; + memset(&input, 0, sizeof(input)); + input.source = CANE_SOURCE_CAMERA; + input.tracking = CANE_TRACKING_NORMAL; + input.camera_authorized = 1; + input.world_tracking_supported = 1; + return input; +} + +static cane_input_t simulation_input(void) { + cane_input_t input; + memset(&input, 0, sizeof(input)); + input.source = CANE_SOURCE_SIMULATION; + input.tracking = CANE_TRACKING_NORMAL; + input.camera_authorized = 1; + input.world_tracking_supported = 1; + return input; +} + +static void test_crc_vector(void) { + const uint8_t digits[] = "123456789"; + expect(cane_crc16(digits, 9) == 0x29B1, "CRC-16/CCITT-FALSE vector"); +} + +static void test_camera_makes_no_hazard_or_route(void) { + cane_input_t input = camera_ready(); + cane_assessment_t assessment; + input.simulation_elevated_hazard = 1; + input.route_cue = CANE_ROUTE_DEMO_LEFT; + input.has_plane_hit = 1; + input.plane_hit_meters = 0.2f; + input.scene_depth_supported = 0; + cane_assess(&input, &assessment); + expect(assessment.source == CANE_SOURCE_CAMERA, "camera source preserved"); + expect(assessment.hazard == CANE_HAZARD_NO_CLAIM, "camera path makes no hazard claim"); + expect(assessment.route_cue == CANE_ROUTE_NONE, "camera path clears route cues"); + expect(assessment.system_unavailable == 0, "normal authorized tracking is available"); + expect(assessment.plane_hit_valid == 1, "close plane hit is recorded as context"); + expect(assessment.plane_hit_cm == 20, "0.2 m plane hit is 20 cm of context"); + expect(assessment.hazard == CANE_HAZARD_NO_CLAIM, "plane hit does not raise a hazard"); +} + +static void test_camera_unavailable_conditions(void) { + cane_assessment_t assessment; + cane_input_t input = camera_ready(); + input.tracking = CANE_TRACKING_LIMITED; + cane_assess(&input, &assessment); + expect(assessment.system_unavailable == 1, "limited tracking is unavailable"); + expect(assessment.hazard == CANE_HAZARD_NO_CLAIM, "limited tracking is not a hazard claim"); + + input = camera_ready(); + input.tracking = CANE_TRACKING_UNAVAILABLE; + cane_assess(&input, &assessment); + expect(assessment.system_unavailable == 1, "unavailable tracking stays unavailable"); + + input = camera_ready(); + input.camera_authorized = 0; + cane_assess(&input, &assessment); + expect(assessment.system_unavailable == 1, "denied camera is unavailable"); + + input = camera_ready(); + input.world_tracking_supported = 0; + input.tracking = CANE_TRACKING_UNSUPPORTED; + cane_assess(&input, &assessment); + expect(assessment.system_unavailable == 1, "unsupported world tracking is unavailable"); + + input = camera_ready(); + input.scene_depth_supported = 0; + cane_assess(&input, &assessment); + expect(assessment.system_unavailable == 0, "missing scene depth alone is not unavailable"); + expect(assessment.hazard == CANE_HAZARD_NO_CLAIM, "missing scene depth is not a hazard"); +} + +static void test_plane_hit_bounds(void) { + cane_assessment_t assessment; + cane_input_t input = camera_ready(); + input.has_plane_hit = 1; + input.plane_hit_meters = 0.0f; + cane_assess(&input, &assessment); + expect(assessment.plane_hit_valid == 0, "zero plane hit is not valid"); + + input.plane_hit_meters = -1.0f; + cane_assess(&input, &assessment); + expect(assessment.plane_hit_valid == 0, "negative plane hit is not valid"); + + input.plane_hit_meters = nanf(""); + cane_assess(&input, &assessment); + expect(assessment.plane_hit_valid == 0, "NaN plane hit is not valid"); + + input.plane_hit_meters = 25.0f; + cane_assess(&input, &assessment); + expect(assessment.plane_hit_valid == 0, "plane hit beyond 20 m is not kept"); + + input.tracking = CANE_TRACKING_LIMITED; + input.plane_hit_meters = 1.5f; + cane_assess(&input, &assessment); + expect(assessment.plane_hit_valid == 0, "plane hit requires normal tracking"); +} + +static void test_simulation_channels_stay_separate(void) { + cane_assessment_t assessment; + cane_input_t input = simulation_input(); + input.simulation_elevated_hazard = 1; + input.simulation_unavailable = 1; + input.route_cue = CANE_ROUTE_DEMO_RIGHT; + input.has_plane_hit = 1; + input.plane_hit_meters = 0.3f; + cane_assess(&input, &assessment); + expect(assessment.source == CANE_SOURCE_SIMULATION, "simulation source preserved"); + expect(assessment.hazard == CANE_HAZARD_ELEVATED, "simulation can request a hazard"); + expect(assessment.system_unavailable == 1, "simulation unavailable is independent"); + expect(assessment.route_cue == CANE_ROUTE_DEMO_RIGHT, "demo route is kept"); + expect(assessment.hazard == CANE_HAZARD_ELEVATED, "route cue does not clear a hazard"); + + input.route_cue = 9; + input.simulation_elevated_hazard = 0; + cane_assess(&input, &assessment); + expect(assessment.route_cue == CANE_ROUTE_NONE, "unknown route value is dropped"); + expect(assessment.hazard == CANE_HAZARD_NO_CLAIM, "simulation without the flag makes no claim"); +} + +static void test_displacement_is_not_velocity(void) { + float meters = 99.0f; + expect(cane_camera_displacement_m(0, 0, 0, 3, 4, 0, 1, &meters) == 1, "3-4-5 displacement is valid"); + expect(meters > 4.999f && meters < 5.001f, "displacement magnitude is 5 m"); + meters = 99.0f; + expect(cane_camera_displacement_m(0, 0, 0, 3, 4, 0, 0, &meters) == 0, "non-normal tracking has no displacement"); + expect(meters == 99.0f, "rejected displacement does not write an output"); + expect(cane_camera_displacement_m(0, 0, 0, 0.0f / 0.0f, 0, 0, 1, &meters) == 0, "NaN pose is rejected"); +} + +static void fill_command(cane_command_t *command, int source, int hazard, int route) { + memset(command, 0, sizeof(*command)); + command->source = source; + command->hazard = hazard; + command->route_cue = route; + command->tracking = CANE_TRACKING_NORMAL; + command->plane_hit_cm = CANE_PLANE_CM_NONE; + command->sequence = 7; + command->time_ms_low = 1234; +} + +static void test_packet_roundtrip_and_rejection(void) { + cane_command_t command; + cane_command_t decoded; + uint8_t packet[CANE_PACKET_BYTES]; + uint8_t altered[CANE_PACKET_BYTES]; + fill_command(&command, CANE_SOURCE_SIMULATION, CANE_HAZARD_ELEVATED, CANE_ROUTE_DEMO_LEFT); + command.system_unavailable = 1; + command.plane_hit_cm = 150; + command.scene_depth_supported = 1; + expect(cane_command_encode(&command, packet) == 1, "simulation command encodes"); + expect(cane_command_decode(packet, CANE_PACKET_BYTES, &decoded) == 1, "simulation command decodes"); + expect(decoded.source == CANE_SOURCE_SIMULATION, "decoded source"); + expect(decoded.hazard == CANE_HAZARD_ELEVATED, "decoded hazard"); + expect(decoded.system_unavailable == 1, "decoded unavailable"); + expect(decoded.route_cue == CANE_ROUTE_DEMO_LEFT, "decoded route"); + expect(decoded.sequence == 7, "decoded sequence"); + expect(decoded.time_ms_low == 1234, "decoded sender time"); + expect(decoded.plane_hit_cm == 150, "decoded plane context"); + expect(decoded.scene_depth_supported == 1, "decoded scene-depth flag"); + + memcpy(altered, packet, sizeof(packet)); + altered[2] ^= 0x01; + expect(cane_command_decode(altered, CANE_PACKET_BYTES, &decoded) == 0, "flipped hazard fails CRC"); + expect(cane_command_decode(packet, CANE_PACKET_BYTES - 1, &decoded) == 0, "short packet is rejected"); + + fill_command(&command, CANE_SOURCE_CAMERA, CANE_HAZARD_ELEVATED, CANE_ROUTE_NONE); + expect(cane_command_admissible(&command) == 0, "camera hazard is not admissible"); + expect(cane_command_encode(&command, packet) == 0, "encoder refuses a camera hazard"); + + fill_command(&command, CANE_SOURCE_CAMERA, CANE_HAZARD_NO_CLAIM, CANE_ROUTE_DEMO_RIGHT); + expect(cane_command_encode(&command, packet) == 0, "encoder refuses a camera route cue"); +} + +static void accept_simulation(cane_link_t *link, int hazard, int unavailable, int route, uint16_t plane_cm, uint32_t now_ms) { + cane_command_t command; + uint8_t packet[CANE_PACKET_BYTES]; + fill_command(&command, CANE_SOURCE_SIMULATION, hazard, route); + command.system_unavailable = unavailable; + command.plane_hit_cm = plane_cm; + expect(cane_command_encode(&command, packet) == 1, "fixture packet encodes"); + expect(cane_link_accept(link, packet, CANE_PACKET_BYTES, now_ms) == 1, "fixture packet accepted"); +} + +static void test_watchdog_and_outputs(void) { + cane_link_t link; + cane_outputs_t at_hazard; + cane_outputs_t at_other_plane; + cane_outputs_t later; + uint8_t bad[CANE_PACKET_BYTES]; + cane_link_init(&link); + cane_link_outputs(&link, 0, &at_hazard); + expect(at_hazard.link_state == CANE_LINK_OUTAGE, "no packet starts in link outage"); + expect(at_hazard.hazard == 0 && at_hazard.unavailable == 0 && at_hazard.route == 0, "outage clears commanded pins"); + expect(at_hazard.link == 1, "outage pattern is on at t=0"); + + accept_simulation(&link, CANE_HAZARD_ELEVATED, 1, CANE_ROUTE_DEMO_LEFT, 80, 1000); + cane_link_outputs(&link, 1000, &at_hazard); + expect(at_hazard.link_state == CANE_LINK_HEARTBEAT, "fresh packet is a heartbeat"); + expect(at_hazard.hazard == 1, "hazard pattern is on at the start of its period"); + expect(at_hazard.unavailable == 1, "unavailable pattern is on at the start of its period"); + expect(at_hazard.route == 1, "route pattern is on at the start of its period"); + expect(at_hazard.link == 0, "healthy link blip is off 1000 ms into its 2000 ms period"); + + accept_simulation(&link, CANE_HAZARD_ELEVATED, 1, CANE_ROUTE_DEMO_LEFT, 400, 1000); + cane_link_outputs(&link, 1000, &at_other_plane); + expect(at_other_plane.hazard == at_hazard.hazard, "plane centimeters do not change hazard output"); + expect(at_other_plane.unavailable == at_hazard.unavailable, "plane centimeters do not change unavailable"); + expect(at_other_plane.route == at_hazard.route, "plane centimeters do not change route"); + expect(at_other_plane.link == at_hazard.link, "plane centimeters do not change link"); + + cane_link_outputs(&link, 1000 + CANE_WATCHDOG_MS, &later); + expect(later.link_state == CANE_LINK_HEARTBEAT, "elapsed watchdog limit is still a heartbeat"); + cane_link_outputs(&link, 1000 + CANE_WATCHDOG_MS + 1, &later); + expect(later.link_state == CANE_LINK_OUTAGE, "one millisecond past the watchdog is an outage"); + expect(later.hazard == 0 && later.unavailable == 0 && later.route == 0, "outage drops the last command"); + + memset(bad, 0, sizeof(bad)); + expect(cane_link_accept(&link, bad, sizeof(bad), 5000) == 0, "corrupt packet is ignored"); + cane_link_outputs(&link, 1000 + CANE_WATCHDOG_MS + 1, &later); + expect(later.link_state == CANE_LINK_OUTAGE, "rejected packet does not refresh the watchdog"); +} + +static void test_patterns(void) { + expect(cane_pulse(0, CANE_LINK_OUT_PERIOD_MS, CANE_LINK_OUT_ON_MS) == 1, "outage pulse starts on"); + expect(cane_pulse(CANE_LINK_OUT_ON_MS, CANE_LINK_OUT_PERIOD_MS, CANE_LINK_OUT_ON_MS) == 0, "outage pulse turns off"); + expect(cane_pulse(0, CANE_LINK_OK_PERIOD_MS, CANE_LINK_OK_ON_MS) == 1, "heartbeat starts with a blip"); + expect(cane_pulse(CANE_LINK_OK_ON_MS, CANE_LINK_OK_PERIOD_MS, CANE_LINK_OK_ON_MS) == 0, "heartbeat blip ends"); + expect(cane_pulse(CANE_HAZARD_ON_MS, CANE_HAZARD_PERIOD_MS, CANE_HAZARD_ON_MS) == 0, "hazard pulse is half period"); +} + +static void test_status_roundtrip(void) { + cane_outputs_t outputs; + cane_status_t status; + uint8_t bytes[CANE_STATUS_BYTES]; + memset(&outputs, 0, sizeof(outputs)); + outputs.link_state = CANE_LINK_OUTAGE; + outputs.link = 1; + expect(cane_status_encode(&outputs, 42, bytes) == 1, "status encodes"); + expect(cane_status_decode(bytes, CANE_STATUS_BYTES, &status) == 1, "status decodes"); + expect(status.link_state == CANE_LINK_OUTAGE, "status link state"); + expect(status.link_on == 1, "status link pin"); + expect(status.hazard_on == 0, "status hazard pin"); + expect(status.last_sequence == 42, "status sequence"); +} + +static void test_assessment_command_is_sendable(void) { + cane_input_t input = camera_ready(); + cane_assessment_t assessment; + cane_command_t command; + uint8_t packet[CANE_PACKET_BYTES]; + input.has_plane_hit = 1; + input.plane_hit_meters = 1.25f; + cane_assess(&input, &assessment); + cane_command_from_assessment(&assessment, 3, 9, &command); + expect(cane_command_encode(&command, packet) == 1, "camera assessment encodes"); + expect(packet[1] == CANE_SOURCE_CAMERA, "packet source is camera"); + expect(packet[2] == CANE_HAZARD_NO_CLAIM, "packet hazard is no claim"); + expect(packet[4] == CANE_ROUTE_NONE, "packet route is none"); +} + +int main(void) { + test_crc_vector(); + test_camera_makes_no_hazard_or_route(); + test_camera_unavailable_conditions(); + test_plane_hit_bounds(); + test_simulation_channels_stay_separate(); + test_displacement_is_not_velocity(); + test_packet_roundtrip_and_rejection(); + test_watchdog_and_outputs(); + test_patterns(); + test_status_roundtrip(); + test_assessment_command_is_sendable(); + if (failures != 0) { + fprintf(stderr, "%d failure(s)\n", failures); + return 1; + } + printf("cane logic tests passed\n"); + return 0; +} diff --git a/scripts/check_workflow.py b/scripts/check_workflow.py index f239c03..e3fb32e 100644 --- a/scripts/check_workflow.py +++ b/scripts/check_workflow.py @@ -18,6 +18,7 @@ "docs/COLLABORATION.md", ".github/PULL_REQUEST_TEMPLATE.md", ".github/ISSUE_TEMPLATE/task.md", + "docs/PROTOTYPE.md", ) REQUIRED_FILES = MARKDOWN_FILES + ( @@ -229,8 +230,8 @@ def validate_workflow(text: str, report: Report) -> None: runs = [value for key, value in walk(data) if key == "run"] if uses != ["actions/checkout@v4"]: report.error(f"workflow must use only actions/checkout@v4, found {uses}") - if runs != ["python3 scripts/check_workflow.py"]: - report.error(f"workflow must run only the local checker, found {runs}") + if runs != ["python3 scripts/check_workflow.py", "make -C prototype test"]: + report.error(f"workflow must run the scaffolding checker and host logic tests, found {runs}") flat = text if "secrets." in flat: report.error("workflow must not reference GitHub secrets")