Bring-up

Arduino Uno Q on macOS, phase by phase

This walkthrough covers bringing PinScope up on real hardware. It is tailored to the Arduino Uno Q on macOS, but most phases apply to any supported board. Each phase has a clear pass criterion. When something fails, capture the exact symptom (error text, screenshot, output) and work backwards from there.

Why this matters

The Uno Q is the most uncertain target because its MCU runs Arduino sketches under Zephyr OS via arduino:zephyr:unoq, not bare-metal classic Arduino. The serial firmware (pinscope.ino) has compile-time guards for this, but runtime behavior of attachInterrupt, Wire.h, and analogReadResolution can still surprise. Go slowly and verify at each layer.

Hardware sanity

Before anything software-related:

Uno Q powered up via USB-C, both LEDs near the USB port lit
The board enumerates in System Information > USB
ls /dev/cu.usbmodem* in Terminal lists at least one device

Pass criterion At least one /dev/cu.usbmodem* device appears.

Likely failure modes

No device shows up: try a different USB-C cable. Many cables are charge-only and don't carry data.
Device disappears after a few seconds: power delivery issue. Try a different port or a powered hub.
Two devices show up: the Uno Q exposes both the Qualcomm Linux side and the STM32U585 MCU side. Both are normal.

Tooling install

Option A: Arduino IDE 2.x

Download Arduino IDE 2.x from arduino.cc (not legacy 1.x)
Tools > Board > Boards Manager: search "uno q"
Install the matching package (exact name varies; expect something like arduino:zephyr)
Tools > Board > Arduino UNO Q
Tools > Port: pick the matching /dev/cu.usbmodem*

Option B: arduino-cli

brew install arduino-cli
arduino-cli core update-index
arduino-cli core search uno
arduino-cli core install arduino:zephyr
arduino-cli board listall | grep -i "uno q"

Pass criterion The board shows up in the board list with FQBN arduino:zephyr:unoq.

Likely failure modes

"Board not found" after install: Boards Manager may not yet expose Uno Q via the public catalog. Workaround: install Arduino App Lab from arduino.cc.
arduino-cli too old: brew upgrade arduino-cli. Anything older than 1.0.0 won't recognize the Zephyr core.

Compile the serial firmware

First real test. Not flashing yet, just confirming the sketch compiles against the Zephyr-based Uno Q core. pinscope.ino has board-detection macros that set PINSCOPE_ADC_BITS = 12 and the right board name for Uno Q automatically. No manual edits should be needed.

cd pinscope
scripts/compile.sh pinscope.ino arduino:zephyr:unoq

Pass criterion Clean compile, no errors. Note the sketch size in the output.

Likely failure modes

attachInterrupt or digitalPinToInterrupt undefined: the Zephyr core is supposed to expose the classic Arduino interrupt API. If not, FREQ mode needs another guard.
Wire.h not found: should be bundled, but if Zephyr renames it (e.g. ZephyrI2C.h), conditional include needed.
analogReadResolution(12) undefined: the PINSCOPE_SET_ADC_RES macro guards the call so we can flip it to 0 for boards that don't support it.
"Sketch too big" or "no upload protocol": library or board config mismatch.

Flash

arduino-cli upload \
  -p /dev/cu.usbmodemXXXX \
  --fqbn arduino:zephyr:unoq \
  /path/to/sketch

Or from the IDE: hit the arrow (Upload).

Pass criterion Upload completes, board reboots. On-board LED behavior may briefly change.

Likely failure modes

1200-bps touch fails: double-tap the reset button on the board to force bootloader mode, then upload.
"Port not found" mid-upload: macOS sometimes reassigns the /dev/cu.usbmodem* number after a reboot. Re-run ls /dev/cu.usbmodem*.

Serial monitor smoke test

Don't open PinScope yet. First confirm the firmware boots and emits sensible output.

Open Serial Monitor at 115200 baud (or screen /dev/cu.usbmodemXXXX 115200)
Send {"cmd":"hello"} + Enter

Pass criterion

{"t":"hello","id":"FI005-XXXX","name":"Arduino Uno Q","hz":10,"adcMax":4095}
{"t":"state","d":[0,0,0,...],"a":[N,N,...],...}

The adcMax:4095 indicates 12-bit ADC reporting. State packets follow every ~100 ms.

Likely failure modes

Nothing at all: serial isn't connecting. Check baud (must be 115200), port, that nothing else is holding the port open.
Garbled text: the firmware came up but at a different baud. Try 9600 or 921600.
Only state lines, no hello: the firmware is alive but missed your command. Try {"cmd":"poll"} to confirm command parsing.

PinScope console connect

Open pinscope.html in Chrome or Edge
Click SERIAL
Pick the same /dev/cu.usbmodem* from the picker
Allow access

Pass criterion Within a second, a device card appears titled "Arduino Uno Q" with an id like FI005-XXXX, tx/rx counters ticking, analog channel bars for A0-A5 wiggling.

Likely failure modes

Picker shows no devices: Web Serial requires HTTPS or file://. Open the HTML file from disk, not http://. Chromium-only.
"Connection failed": another process has the port open. Close the Arduino IDE Serial Monitor and try again.
No state updates: tx counter goes up, rx stays at zero. The browser is sending but the firmware isn't responding. Re-check Phase 4.

Pin control round-trip

First real interactive test:

Click D13's mode badge until it reads OUT
Click the toggle button. The on-board user LED should light
Click again, LED off

Pass criterion LED responds to clicks within ~100 ms.

Analog + strip chart

Click the A0 chip in the trace selector under the strip chart
Touch A0 with your finger (picks up ~60 Hz hum)
Connect A0 to ground briefly: trace drops to 0
Connect A0 to 3.3V: trace pegs

Pass criterion Trace responds instantly, values match expected scale (0-4095 for Uno Q's 12-bit ADC, since the hello packet's adcMax drove the auto-detect).

Likely failure modes

Flat line at 0 or 4095: ADC isn't being read, or analogRead(A0+i) doesn't work on this board.
Values stuck in 0-1023 range when board should be 12-bit: adcMax in the hello packet didn't propagate. Manually click the "12" toggle as a workaround and tell me (that's a real bug to fix).

PWM

Click D11 mode badge to cycle to PWM
Drag the slider from 0 to 255
With an LED + resistor on D11, watch the brightness ramp

Pass criterion Smooth ramp, no flicker steps.

FREQ mode

Wire D2 to D11 with a jumper (D11 still in PWM from Phase 8)
Cycle D2's mode to FREQ
D2's face should show a Hz reading

Pass criterion Hz value matches PWM frequency on the Uno Q.

Likely failure modes

"no interrupt on pin": digitalPinToInterrupt(2) returned NOT_AN_INTERRUPT. Try D3. If all pins fail, the Zephyr core doesn't expose the classic interrupt API and FREQ needs a native implementation.
"0 Hz" persistently: ISR is attached but never firing. Edge polarity or signal-level issue.

I2C scan

Skip this if you don't have a Qwiic device handy.

Wire SDA/SCL/GND/3V3 to an I2C device (BME280, MPU6050, etc.)
Click SCAN BUS
Grid should highlight the address(es)

Pass criterion At least one address lights up.

Likely failure modes

Empty scan: wiring (pull-ups? supply voltage? SDA/SCL swapped?), or Wire library on Uno Q uses different default pins.

Session save + replay

Non-hardware sanity checks:

Set up a couple of pins, calibrate A0, add a threshold alert
Click EXPORT, save the JSON file
Reload pinscope.html
Reconnect, confirm the session restored from localStorage
Click CAPTURE, disconnect, click REPLAY, pick the JSON
A [replay] card appears with the captured trace looping

What success looks like

Phases 1-8 all green means the core PinScope experience works on Uno Q. Phases 9-11 are bonus and tell you how complete the Zephyr-core compatibility is.

After bring-up, possible next steps:

Patching pinscope.ino for any Uno Q quirks you found
Updating the README to remove "experimental" from the Uno Q claim
BLE bring-up on Uno Q (or punt to a more confirmed BLE target like Nano 33 IoT)
A short blog post or video walkthrough

When you get stuck

The structure of a useful bug report:

Which phase you got to
What the expected pass criterion was
What actually happened (exact text or screenshot)
The relevant Wire Log entries if any

File at github.com/mbparks/pinscope/issues.