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
73 changes: 73 additions & 0 deletions .github/workflows/prototype-build.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# Compiles the native iPhone app and the UNO R4 WiFi sketch.
# The phone still processes video locally at runtime. These jobs do not
# sign, install, flash, or run inference.

name: Prototype builds

on:
pull_request:
push:
branches: [main]
workflow_dispatch:

permissions:
contents: read

concurrency:
group: prototype-builds-${{ github.ref }}
cancel-in-progress: true

jobs:
ios-unsigned:
name: Unsigned iOS compile
runs-on: macos-latest
timeout-minutes: 30
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Compile without signing
run: |
set -euo pipefail
xcodebuild -version
xcodebuild \
-project prototype/ios/CaneDemo/CaneDemo.xcodeproj \
-scheme CaneDemo \
-configuration Debug \
-destination "generic/platform=iOS" \
CODE_SIGNING_ALLOWED=NO \
CODE_SIGNING_REQUIRED=NO \
CODE_SIGN_IDENTITY="" \
DEVELOPMENT_TEAM="" \
build

firmware:
name: UNO R4 WiFi compile
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Install Arduino CLI 1.5.1
run: |
set -euo pipefail
url="https://github.com/arduino/arduino-cli/releases/download/v1.5.1/arduino-cli_1.5.1_Linux_64bit.tar.gz"
sha="28a8e119c498a25607821c36cb2dc49e8463941b261a0d99091baa7bc692dd2b"
curl -fsSL -o "$RUNNER_TEMP/arduino-cli.tar.gz" "$url"
echo "${sha} $RUNNER_TEMP/arduino-cli.tar.gz" | sha256sum -c -
mkdir -p "$RUNNER_TEMP/arduino-cli" "$RUNNER_TEMP/bin"
tar -xzf "$RUNNER_TEMP/arduino-cli.tar.gz" -C "$RUNNER_TEMP/arduino-cli"
install -m 0755 "$RUNNER_TEMP/arduino-cli/arduino-cli" "$RUNNER_TEMP/bin/arduino-cli"
echo "$RUNNER_TEMP/bin" >> "$GITHUB_PATH"
"$RUNNER_TEMP/bin/arduino-cli" version
- name: Install Renesas core 1.6.0 and ArduinoBLE 2.1.0
run: |
set -euo pipefail
arduino-cli core update-index
arduino-cli core install arduino:renesas_uno@1.6.0
arduino-cli lib install "ArduinoBLE@2.1.0"
arduino-cli core list
arduino-cli lib list
- name: Compile UNO R4 WiFi sketch
run: |
set -euo pipefail
arduino-cli compile --fqbn arduino:renesas_uno:unor4wifi --warnings all prototype/firmware/uno_r4_wifi
5 changes: 3 additions & 2 deletions 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. 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.
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.

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 @@ -133,7 +133,8 @@ 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, 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.
- [`.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.

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

Expand Down
45 changes: 29 additions & 16 deletions docs/PROTOTYPE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ This is a controlled demo for MakeUC Hackathon 2026. A sighted supervisor wears

The phone warns with uncertainty. It does not invent a safe path. A quiet hazard channel is not an all-clear.

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.

## Fixed demo requirements

- The phone is body-mounted. This repository does not design the mount.
Expand All @@ -24,15 +26,15 @@ No monocular depth network is bundled. A relative-depth model would not be an ho

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).
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/) 2.1.0 documents peripheral and central modes and names the UNO R4 WiFi. Its README says that board needs ESP32-S3 firmware 0.2.0 or newer. The compile job pins Arduino core `arduino:renesas_uno` 1.6.0, whose `unor4wifi` board id is the UNO R4 WiFi. This firmware is a BLE peripheral only. It does not call the Wi-Fi API. The board package still compiles its WiFiS3 library while building ArduinoBLE for this board. That compile dependency is not a second radio session. 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.
The simulation path is a separate bench control on the phone. It can request the D2 hazard actuator, the D3 unavailable actuator, and a D4 left or right label. The screen says the input is simulated. Those controls do not read the camera and do not mean an obstacle was detected. 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.

Expand Down Expand Up @@ -95,35 +97,46 @@ The phone timer asks to send about ten times a second. That is the timer interva
- BLE pairing.
- An iOS binary or a flashed board. This environment has no Xcode and no Arduino toolchain.

## Checks that were run here
## Checks

From the repository root:
Host logic tests, from a machine with a C compiler:

```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.
`make` compiles `cane_logic.c` and runs [test_cane.c](../prototype/tests/test_cane.c). Those tests do not open a camera, a radio, or a GPIO.

[prototype-build.yml](../.github/workflows/prototype-build.yml) adds two cloud compile jobs. They use the repository contents only. They do not use a signing certificate, an Apple team, or a secret.

- Unsigned iOS compile: a GitHub-hosted `macos-latest` runner runs `xcodebuild` with code signing disabled. A successful log means the sources compiled. It does not produce an app that can be installed on the iPhone.
- UNO R4 WiFi compile: a GitHub-hosted `ubuntu-latest` runner installs Arduino CLI 1.5.1, core `arduino:renesas_uno` 1.6.0, and ArduinoBLE 2.1.0, then compiles the sketch for `arduino:renesas_uno:unor4wifi`. A successful log means the sketch compiled. It does not flash the board.

## Build the iPhone app
## Build without owning a Mac

Use a Mac with Xcode 16 or newer and an iOS 18 SDK.
The unsigned iOS job is the compile check for someone who does not have a Mac. Watch that job on the pull request. A green result is a compile result. Copying the runner's build products to the phone will not install them, because the phone requires a signature from an Apple development team.

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.
Installing the app on the iPhone 16 is a separate human step:

1. A person with a Mac and Xcode opens [CaneDemo.xcodeproj](../prototype/ios/CaneDemo/CaneDemo.xcodeproj/project.pbxproj).
2. In Signing & Capabilities, that person selects their own Apple team. This repository has no team id, certificate, or provisioning profile.
3. They change `com.makeuc2026.canedemo` if their team cannot use that bundle id.
4. They connect the standard iPhone 16, trust the computer, and enable Developer Mode.
5. They run the signed build on that phone. The iOS Simulator is not a stand-in for this phone's camera, motion, or the BLE peripheral.
6. On the phone, scene depth support should read no. If it reads yes, the device is the wrong model. This build still does not enable scene depth.

Apple Developer Program enrollment, certificate creation, and signing stay with that person. This repository does not buy or enroll an Apple account.

## Flash the UNO R4 WiFi

The firmware job only compiles. Flashing is still local:

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.
2. Install the Arduino UNO R4 Boards package at 1.6.0, or a newer package you choose after reading its notes, and select Arduino UNO R4 WiFi.
3. Install ArduinoBLE 2.1.0. The library lists this board and asks for ESP32-S3 firmware 0.2.0 or newer. Let the board package update that bridge firmware if it offers to.
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.
5. Open Serial Monitor at 115200. Before the phone connects, the log should show the link outage pattern.

## Supervised demo

Expand Down
8 changes: 8 additions & 0 deletions prototype/firmware/uno_r4_wifi/cane_logic.h
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@
#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/*
* Shared claim, packet, and actuator-output logic for the supervised demo.
* Obstacle distance, speed, and time-to-contact are not represented.
Expand Down Expand Up @@ -164,4 +168,8 @@ 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);

#ifdef __cplusplus
}
#endif

#endif
6 changes: 3 additions & 3 deletions prototype/firmware/uno_r4_wifi/uno_r4_wifi.ino
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,11 @@
static BLEService caneService("8f3a1c20-7b6e-4d5a-9c11-6e2f0a9b1001");
static BLECharacteristic commandCharacteristic(
"8f3a1c20-7b6e-4d5a-9c11-6e2f0a9b1002",
BLEWrite | BLEWriteWithoutResponse,
static_cast<uint16_t>(BLEWrite | BLEWriteWithoutResponse),
CANE_PACKET_BYTES);
static BLECharacteristic statusCharacteristic(
"8f3a1c20-7b6e-4d5a-9c11-6e2f0a9b1003",
BLERead | BLENotify,
static_cast<uint16_t>(BLERead | BLENotify),
CANE_STATUS_BYTES);

static cane_link_t link;
Expand Down Expand Up @@ -67,7 +67,7 @@ static void apply_outputs(uint32_t now_ms) {
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);
statusCharacteristic.writeValue(status, static_cast<int>(CANE_STATUS_BYTES));
last_status_ms = now_ms;
}
}
Expand Down
17 changes: 10 additions & 7 deletions prototype/ios/CaneDemo/CaneDemo/DebugRootView.swift
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ struct DebugRootView: View {
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.")
Text("Not a mobility aid. The existing cane stays in use. Video stays on this iPhone. 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)
Expand Down Expand Up @@ -80,16 +80,19 @@ struct DebugRootView: View {

private var simulationSection: some View {
VStack(alignment: .leading, spacing: 8) {
Text("Simulation controls")
Text("Actuator bench test")
.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("These switches send a simulated packet. They do not read the camera and they do not detect an obstacle.")
Toggle("D2 hazard actuator", isOn: $demo.simulatedHazard)
.accessibilityLabel("Simulated D2 hazard actuator")
Toggle("D3 unavailable actuator", isOn: $demo.simulatedUnavailable)
.accessibilityLabel("Simulated D3 unavailable actuator")
Picker("D4 route actuator label", selection: $demo.simulatedRoute) {
Text("Off").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.")
Text("D4 only means a manual left or right label is active. Neither label is a clear direction. D5 is the link actuator. The board pulses it. Disconnect Bluetooth to test the outage pattern.")
.font(.footnote)
}
.onChange(of: demo.simulatedHazard) { _, _ in demo.refreshClaim() }
Expand Down
Loading
Loading