Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions .github/workflows/pages.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Publishes the static Bluefy page after a push to main.
# It does not run on pull requests, does not sign an app, and does not
# change the phone runtime. GitHub Pages still has to be switched to
# GitHub Actions by a person before a deploy can succeed.

name: Pages

on:
push:
branches: [main]

permissions:
contents: read
pages: write
id-token: write

concurrency:
group: pages
cancel-in-progress: true

jobs:
deploy:
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
name: Publish web page
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
timeout-minutes: 10
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Upload web folder
uses: actions/upload-pages-artifact@v5
with:
path: web
- name: Deploy
id: deployment
uses: actions/deploy-pages@v5
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,6 @@ Shared instructions for the owner, one teammate, Cursor, and Claude Code: [docs/

Supervised iPhone 16 and UNO R4 WiFi cane demo: [docs/PROTOTYPE.md](docs/PROTOTYPE.md).

Bluefy web page, still processed on the phone: [web/index.html](web/index.html). Walkthrough: [docs/WEB_DEMO.md](docs/WEB_DEMO.md).

Host logic tests, with no phone or board required: `make -C prototype test`.
3 changes: 2 additions & 1 deletion docs/COLLABORATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. One job validates these workflow files and runs the host cane-logic tests. Another job compiles the unsigned iOS app and the UNO R4 WiFi sketch. Those jobs do not sign, install, or flash anything, and they do not certify the demo as safe. Runtime video stays on the phone.
In the pull request, name the review steps and the command you ran. One job validates these workflow files and runs the host cane-logic tests. Another job compiles the unsigned iOS app and the UNO R4 WiFi sketch. A Pages workflow can publish the static web folder only from `main` after a person selects GitHub Actions as the Pages source. Those jobs do not sign, install, or flash the phone app, and they do not certify the demo as safe. Runtime video stays on the phone.

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.

Expand Down Expand Up @@ -135,6 +135,7 @@ Issue and pull request template behavior is documented in [About issue and pull
- [`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, 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. That workflow installs nothing and reads no secrets.
- [`.github/workflows/prototype-build.yml`](../.github/workflows/prototype-build.yml) compiles the unsigned iPhone app on a GitHub-hosted Mac and compiles the UNO R4 WiFi sketch on Linux. It reads repository contents only. It does not sign or install the app.
- [`.github/workflows/pages.yml`](../.github/workflows/pages.yml) publishes `web/` with GitHub's Pages actions after a push to `main`. It does not run for pull requests.

After changing any of these files, run this from the repository root:

Expand Down
2 changes: 2 additions & 0 deletions docs/PROTOTYPE.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ The phone warns with uncertainty. It does not invent a safe path. A quiet hazard

At runtime the path is the iPhone 16, then Bluetooth LE, then the UNO R4 WiFi, then the four actuator drivers. The phone processes the camera and motion on the device. No laptop and no cloud service infer a hazard. GitHub Actions can compile the unsigned app and the sketch. That compile job is not part of the running demo.

The Bluefy page in [docs/WEB_DEMO.md](WEB_DEMO.md) is the path that can run without a Mac. It keeps video on the phone. Its hazard uses a separate image-heuristic packet. The native camera packet still cannot carry an elevated hazard.

## Fixed demo requirements

- The phone is body-mounted. This repository does not design the mount.
Expand Down
43 changes: 43 additions & 0 deletions docs/WEB_DEMO.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Bluefy page

The page is [web/index.html](../web/index.html). It is the phone runtime for this increment. A standard iPhone 16, with Bluefy installed by you, opens the page. The page uses the rear camera, runs COCO-SSD in the browser, and writes the existing 18-byte Bluetooth packet to the UNO R4 WiFi. A laptop is not part of that runtime.

This repository has not run that combination on a phone. A green test log is not a Bluefy result.

## What the packet means

The native camera path still cannot send an elevated hazard. The web page uses a separate source, image heuristic, value 3.

- D2 pulses only for an elevated claim. From the web page that means a supported box is in the center of the picture, or you turned on the manual D2 switch. It is not a measured collision.
- D3 pulses when the camera, model, or page is not ready. Quiet D3 is not an all-clear.
- D4 pulses only for a manual left or right label. That label is not a clear direction.
- D5 is driven by the board. A short blip means packets are arriving. A fast pattern means the 500 ms watchdog expired. The page tries to send every 200 ms while it is connected.

The image-heuristic packet is rejected if it contains a distance or a route. The model does not report meters, speed, or time to contact. If the model fails, the page shows the error and does not invent a warning from brightness.

## Software already in the repo

- Sketch: [prototype/firmware/uno_r4_wifi/uno_r4_wifi.ino](../prototype/firmware/uno_r4_wifi/uno_r4_wifi.ino)
- The compile job that passed on the previous pull request used Arduino CLI 1.5.1, board package `arduino:renesas_uno` 1.6.0, and ArduinoBLE 2.1.0. This page keeps those versions.
- Pick the board Arduino UNO R4 WiFi. The sketch calls `Serial.begin(115200)` and prints `Cane demo controller`, `Advertising CaneDemo as a BLE peripheral.`, `accepted source=`, and `rejected packet`.
- Pinned browser downloads, only when you tap Load object model: TensorFlow.js 4.22.0 and COCO-SSD 2.2.3 from jsDelivr, both Apache-2.0. The weights are the library's `lite_mobilenet_v2` files at `https://storage.googleapis.com/tfjs-models/savedmodel/ssdlite_mobilenet_v2/model.json`. The camera picture is not sent anywhere.

## What only you can do

1. Merge the pull request.
2. In the repository Settings, open Pages, and set the source to GitHub Actions. The workflow [pages.yml](../.github/workflows/pages.yml) does not run for a pull request, and it cannot switch that setting. Until that source is selected, there is no published page. `https://pschmeln.github.io/agent-workflow/` returned 404 when this branch was prepared.
3. After the Pages job on `main` succeeds, open the URL printed by that job in Bluefy on the iPhone 16. Do not type a guessed address.
4. Install Bluefy yourself. Flash the sketch. Wire four external drivers to D2, D3, D4, and D5. Do not power actuators from the header pins.
5. With a sighted spotter, use the page sections one at a time, then the combined switch. Background the app and confirm D5 changes to the fast pattern. Do not cover anyone's eyes.

## Actuator check

| What you do | What should move |
| --- | --- |
| Phone not connected | D5 fast, D2 D3 D4 off |
| Connected, no manual switch and no combined warning | D3 unavailable pattern, D5 slow blip |
| Manual D2 | D2 pulses, serial `source=simulation` |
| Manual D4 left or right label | D4 pulses. The label is not a safe turn |
| Combined warning on, supported object in the center box | D2 pulses, serial `source=image-heuristic` |
| Combined warning on, nothing in the center | D2 off. The page says this is not an all-clear |
| Leave Bluefy or disconnect | D5 fast within about a second |
8 changes: 7 additions & 1 deletion prototype/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,18 @@ CFLAGS ?= -std=c11 -Wall -Wextra -Werror -I firmware/uno_r4_wifi

.PHONY: test clean

test: build/test_cane
test: build/test_cane build/print_fixture
./build/test_cane
./build/print_fixture > build/packets.json
node --test ../web/logic.test.mjs

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

build/print_fixture: firmware/uno_r4_wifi/cane_logic.c firmware/uno_r4_wifi/cane_logic.h tests/print_fixture.c
mkdir -p build
$(CC) $(CFLAGS) -o $@ firmware/uno_r4_wifi/cane_logic.c tests/print_fixture.c -lm

clean:
rm -rf build
21 changes: 20 additions & 1 deletion prototype/firmware/uno_r4_wifi/cane_logic.c
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,19 @@ void cane_assess(const cane_input_t *in, cane_assessment_t *out) {
return;
}

if (in->source == CANE_SOURCE_IMAGE_HEURISTIC) {
clear_plane(out);
out->route_cue = CANE_ROUTE_NONE;
if (!in->image_pipeline_ready) {
out->system_unavailable = 1;
out->hazard = CANE_HAZARD_NO_CLAIM;
return;
}
out->system_unavailable = 0;
out->hazard = in->image_heuristic_elevated ? CANE_HAZARD_ELEVATED : CANE_HAZARD_NO_CLAIM;
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;
Expand Down Expand Up @@ -148,7 +161,8 @@ void cane_command_from_assessment(
}

int cane_command_admissible(const cane_command_t *command) {
if (command->source != CANE_SOURCE_CAMERA && command->source != CANE_SOURCE_SIMULATION) {
if (command->source != CANE_SOURCE_CAMERA && command->source != CANE_SOURCE_SIMULATION &&
command->source != CANE_SOURCE_IMAGE_HEURISTIC) {
return 0;
}
if (command->hazard != CANE_HAZARD_NO_CLAIM && command->hazard != CANE_HAZARD_ELEVATED) {
Expand All @@ -169,6 +183,11 @@ int cane_command_admissible(const cane_command_t *command) {
return 0;
}
}
if (command->source == CANE_SOURCE_IMAGE_HEURISTIC) {
if (command->route_cue != CANE_ROUTE_NONE || command->plane_hit_cm != CANE_PLANE_CM_NONE) {
return 0;
}
}
return 1;
}

Expand Down
5 changes: 4 additions & 1 deletion prototype/firmware/uno_r4_wifi/cane_logic.h
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,8 @@ extern "C" {

enum {
CANE_SOURCE_CAMERA = 1,
CANE_SOURCE_SIMULATION = 2
CANE_SOURCE_SIMULATION = 2,
CANE_SOURCE_IMAGE_HEURISTIC = 3
};

enum {
Expand Down Expand Up @@ -84,6 +85,8 @@ typedef struct {
int simulation_elevated_hazard;
int simulation_unavailable;
int route_cue;
int image_heuristic_elevated;
int image_pipeline_ready;
} cane_input_t;

typedef struct {
Expand Down
22 changes: 22 additions & 0 deletions prototype/firmware/uno_r4_wifi/uno_r4_wifi.ino
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,24 @@ static void set_pin_low(int pin) {
digitalWrite(pin, LOW);
}

static const char *source_name(int source) {
if (source == CANE_SOURCE_CAMERA) {
return "camera";
}
if (source == CANE_SOURCE_SIMULATION) {
return "simulation";
}
if (source == CANE_SOURCE_IMAGE_HEURISTIC) {
return "image-heuristic";
}
return "unknown";
}

static void print_outputs(uint32_t now_ms, const cane_outputs_t *out) {
Serial.print("ms=");
Serial.print(now_ms);
Serial.print(" source=");
Serial.print(source_name(link.command.source));
Serial.print(" link=");
Serial.print(out->link_state == CANE_LINK_OUTAGE ? "outage" : "heartbeat");
Serial.print(" pins hazard=");
Expand Down Expand Up @@ -112,6 +127,13 @@ void loop() {
Serial.print("ms=");
Serial.print(now_ms);
Serial.println(" rejected packet");
} else {
Serial.print("ms=");
Serial.print(now_ms);
Serial.print(" accepted source=");
Serial.print(source_name(link.command.source));
Serial.print(" seq=");
Serial.println(link.command.sequence);
}
}
}
Expand Down
4 changes: 3 additions & 1 deletion prototype/ios/CaneDemo/CaneDemo/DemoController.swift
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,9 @@ final class DemoController: NSObject, ObservableObject, ARSessionDelegate, CBCen
plane_hit_meters: 0,
simulation_elevated_hazard: 0,
simulation_unavailable: 0,
route_cue: Int32(CANE_ROUTE_NONE)
route_cue: Int32(CANE_ROUTE_NONE),
image_heuristic_elevated: 0,
image_pipeline_ready: 0
)
if sourceIsSimulation {
input.simulation_elevated_hazard = Int32(simulatedHazard ? 1 : 0)
Expand Down
46 changes: 46 additions & 0 deletions prototype/tests/print_fixture.c
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
#include "cane_logic.h"

#include <stdio.h>
#include <string.h>

static void emit(const char *name, const cane_command_t *command, int last) {
uint8_t bytes[CANE_PACKET_BYTES];
int ok = cane_command_encode(command, bytes);
size_t i;
printf(" {\"name\":\"%s\",\"ok\":%d,\"bytes\":[", name, ok);
if (ok) {
for (i = 0; i < CANE_PACKET_BYTES; i++) {
printf("%s%u", i == 0 ? "" : ",", bytes[i]);
}
}
printf("]}%s\n", last ? "" : ",");
}

static cane_command_t command_for(int source, int hazard, int unavailable, int route, uint16_t plane_cm) {
cane_command_t command;
memset(&command, 0, sizeof(command));
command.source = source;
command.hazard = hazard;
command.system_unavailable = unavailable;
command.route_cue = route;
command.tracking = CANE_TRACKING_NORMAL;
command.plane_hit_cm = plane_cm;
command.sequence = 9;
command.time_ms_low = 200;
return command;
}

int main(void) {
cane_command_t simulation = command_for(
CANE_SOURCE_SIMULATION, CANE_HAZARD_ELEVATED, 0, CANE_ROUTE_DEMO_LEFT, CANE_PLANE_CM_NONE);
cane_command_t image = command_for(
CANE_SOURCE_IMAGE_HEURISTIC, CANE_HAZARD_ELEVATED, 0, CANE_ROUTE_NONE, CANE_PLANE_CM_NONE);
cane_command_t camera = command_for(
CANE_SOURCE_CAMERA, CANE_HAZARD_NO_CLAIM, 1, CANE_ROUTE_NONE, CANE_PLANE_CM_NONE);
printf("[\n");
emit("simulation", &simulation, 0);
emit("image", &image, 0);
emit("camera", &camera, 1);
printf("]\n");
return 0;
}
42 changes: 42 additions & 0 deletions prototype/tests/test_cane.c
Original file line number Diff line number Diff line change
Expand Up @@ -283,6 +283,47 @@ static void test_assessment_command_is_sendable(void) {
expect(packet[4] == CANE_ROUTE_NONE, "packet route is none");
}

static void test_image_heuristic_is_not_a_distance(void) {
cane_input_t input = camera_ready();
cane_assessment_t assessment;
cane_command_t command;
uint8_t packet[CANE_PACKET_BYTES];

input.image_heuristic_elevated = 1;
cane_assess(&input, &assessment);
expect(assessment.source == CANE_SOURCE_CAMERA, "camera source ignores the image flag");
expect(assessment.hazard == CANE_HAZARD_NO_CLAIM, "camera source still cannot raise a hazard");

input = camera_ready();
input.source = CANE_SOURCE_IMAGE_HEURISTIC;
input.image_pipeline_ready = 1;
input.image_heuristic_elevated = 1;
input.has_plane_hit = 1;
input.plane_hit_meters = 0.4f;
input.route_cue = CANE_ROUTE_DEMO_RIGHT;
cane_assess(&input, &assessment);
expect(assessment.hazard == CANE_HAZARD_ELEVATED, "fresh image heuristic can raise a hazard");
expect(assessment.system_unavailable == 0, "fresh image pipeline is available");
expect(assessment.route_cue == CANE_ROUTE_NONE, "image heuristic drops a route cue");
expect(assessment.plane_hit_valid == 0, "image heuristic drops a plane distance");
cane_command_from_assessment(&assessment, 4, 50, &command);
expect(cane_command_encode(&command, packet) == 1, "image heuristic packet encodes");
expect(packet[1] == CANE_SOURCE_IMAGE_HEURISTIC, "packet source is image heuristic");
expect(packet[14] == 0xFF && packet[15] == 0xFF, "image heuristic packet has no distance");

input.image_pipeline_ready = 0;
cane_assess(&input, &assessment);
expect(assessment.hazard == CANE_HAZARD_NO_CLAIM, "stale image pipeline clears the hazard");
expect(assessment.system_unavailable == 1, "stale image pipeline is unavailable");

fill_command(&command, CANE_SOURCE_IMAGE_HEURISTIC, CANE_HAZARD_ELEVATED, CANE_ROUTE_DEMO_LEFT);
command.plane_hit_cm = CANE_PLANE_CM_NONE;
expect(cane_command_encode(&command, packet) == 0, "image heuristic route is rejected");
fill_command(&command, CANE_SOURCE_IMAGE_HEURISTIC, CANE_HAZARD_ELEVATED, CANE_ROUTE_NONE);
command.plane_hit_cm = 30;
expect(cane_command_encode(&command, packet) == 0, "image heuristic distance is rejected");
}

int main(void) {
test_actuator_pins();
test_crc_vector();
Expand All @@ -296,6 +337,7 @@ int main(void) {
test_patterns();
test_status_roundtrip();
test_assessment_command_is_sendable();
test_image_heuristic_is_not_a_distance();
if (failures != 0) {
fprintf(stderr, "%d failure(s)\n", failures);
return 1;
Expand Down
Loading
Loading