Tutorial: First Serial Scan¶

This tutorial assumes the ESP32-S3 firmware is loaded and the spectrometer is visible as a serial port.

1. Find the Port¶

macOS usually exposes boards as /dev/tty.usbmodem* or /dev/tty.usbserial*.

ls /dev/tty.usb*

2. Capture One JSON Frame¶

python tools/read_luxnode_serial.py /dev/tty.usbmodem1101 --command SCAN --out scan.json

3. Inspect With the SDK¶

luxspec inspect-frame scan.json

4. Stream Frames Live¶

List likely Luxnode serial ports:

luxspec ports

Stream 100 frames and append them to a JSONL run log:

luxspec stream --port /dev/tty.usbmodem1101 --stream-interval-ms 250 --log runs/first-light.jsonl --frames 100

Serve the same stream to a browser or website over Server-Sent Events:

luxspec stream --port /dev/tty.usbmodem1101 --stream-interval-ms 250 --http-port 8765 --log runs/first-light.jsonl

Open http://127.0.0.1:8765 for the built-in live viewer. Other dashboards can subscribe to http://127.0.0.1:8765/events.

5. Capture Calibration Frames¶

python tools/read_luxnode_serial.py /dev/tty.usbmodem1101 --command DARK --out dark.json
python tools/read_luxnode_serial.py /dev/tty.usbmodem1101 --command WHITE --out white.json
python tools/read_luxnode_serial.py /dev/tty.usbmodem1101 --command SCAN --out sample.json

Treat the first scan after power-up as disposable. The firmware already flushes once, but repeated first-light checks are useful while hardware is changing.

6. Run The Prototype Measurement Command¶

luxspec measure --port /dev/tty.usbmodem1101 --mode reflectance --module minerals --out runs/mineral-first-light.json

The output JSON contains the dark/reference/sample frames, processed spectra, peaks, module metrics, and readiness checks.