ykcheungab
223 lines
10 KiB
Markdown
223 lines
10 KiB
Markdown
# UART finger service
|
|
|
|
Connect 1-4 sources individually through UART, or load an explicit setup file
|
|
with their configurations and calibration paths. There is no camera discovery
|
|
or hot-plug monitoring; every source is selected by the user.
|
|
|
|
## Start the service and add cameras
|
|
|
|
In the Q6A TTL login shell, activate the board environment prepared by
|
|
`setup/sdk_setup.sh`. It needs Python 3.10+, the `orisys` SDK and `pyserial`.
|
|
From the board's `dragon-q6a` directory:
|
|
|
|
```bash
|
|
python serial/example_uart.py --port /dev/ttyHS1 --config finger
|
|
```
|
|
|
|
The service opens only the data UART and replies `OK ready 0`. No camera is
|
|
opened and no measurement is sent until the host adds a source and starts output.
|
|
Send these lines through the data UART, waiting for each reply:
|
|
|
|
```text
|
|
add /dev/video0
|
|
OK added 1
|
|
add /dev/video2
|
|
OK added 2
|
|
start
|
|
OK start
|
|
force,1,1.250000,-2.500000,3.750000
|
|
force,2,0.500000,0.100000,-0.200000
|
|
```
|
|
|
|
Use actual capture nodes; the paths above are examples. One USB camera can expose
|
|
multiple `/dev/video*` nodes, so do not assume every node represents a different
|
|
camera. `v4l2-ctl --list-devices` shows device groups. Select one usable capture
|
|
node per camera. Camera indices such as `add 0` are also accepted. Sources must
|
|
be distinct; `0` and `/dev/video0` are treated as the same camera.
|
|
|
|
The first successful addition is sensor 1, the next sensor 2, up to sensor 4.
|
|
No sensor count is declared in advance. A failed addition replies `ERR add ...`,
|
|
closes its newly opened runtime if one exists, and leaves existing cameras and
|
|
IDs unchanged. It does not consume an ID. The service remains available for retry.
|
|
|
|
To select this sensor's force calibration, append `--calibration`:
|
|
|
|
```text
|
|
add /dev/video0 --calibration "/home/radxa/calibrations/finger/DD02-14.json"
|
|
```
|
|
|
|
An optional config still works: `add SOURCE CONFIG --calibration PATH`.
|
|
Explicit calibration paths are passed to SDK `FingerRuntime.open(cal_path=...)`.
|
|
A missing or invalid file fails the addition, without falling back to raw values.
|
|
Without the option, normal SDK calibration selection applies. This does not
|
|
replace calibration on a camera already added; restart to change that mapping.
|
|
|
|
The Windows example `D:\orisys_ws\data\calibrations\finger\DD02-14.json` refers
|
|
to a file on that computer. Copy it to the Q6A before using a board-local path.
|
|
Quote Windows paths in UART commands, or use forward slashes. The user must
|
|
match each camera to its physical sensor's calibration; no serial-number discovery
|
|
is performed.
|
|
|
|
The TTL login console and data UART must use **different ports**. Data defaults
|
|
to `/dev/ttyHS1`, 115200 baud, 8N1 without flow control. It must not be occupied
|
|
by getty or another serial program. The script does not configure UART pins.
|
|
Logs stay in the login console; protocol records go to the data UART.
|
|
`--show` is optional local desktop debugging.
|
|
|
|
## Batch setup and one-command startup
|
|
|
|
Copy [sensors.example.json](../serial/sensors.example.json), then replace its
|
|
camera paths and calibration filenames with the real mappings. `SENSOR-2` through
|
|
`SENSOR-4` are placeholders. The JSON format is:
|
|
|
|
```json
|
|
{
|
|
"sensors": [
|
|
{"source": "/dev/video0", "config": "finger", "calibration": "calibrations/finger/DD02-14.json"},
|
|
{"source": "/dev/video2", "calibration": "calibrations/finger/SENSOR-2.json"}
|
|
]
|
|
}
|
|
```
|
|
|
|
List 1-4 entries. `source` is required; `config` defaults to startup `--config`.
|
|
An omitted/null `calibration` uses normal SDK selection. Relative file paths
|
|
resolve from the setup file's directory, independently of the working directory.
|
|
Named configs such as `finger` remain names. Unknown fields are rejected.
|
|
|
|
Once saved as `sensors.json`, one terminal command connects the whole set and
|
|
starts continuous UART output:
|
|
|
|
```bash
|
|
python serial/example_uart.py --port /dev/ttyHS1 --setup sensors.json --start
|
|
```
|
|
|
|
Omit `--start` to connect and wait for UART commands. With neither option, empty
|
|
manual startup is unchanged. `--start` requires `--setup`. Preparation failure
|
|
rolls back the entire startup set and exits before opening the UART.
|
|
|
|
An already-running service can also load the file:
|
|
|
|
```text
|
|
load "/home/radxa/sensors.json"
|
|
OK loaded 1 2
|
|
start
|
|
```
|
|
|
|
`load` only connects; it does not start output. It can extend manually added
|
|
sensors, up to four total. Batch failure removes only that batch's new sensors
|
|
and leaves previously added cameras unchanged. `add` and `load` require stopped
|
|
output. Wait for each reply before proceeding.
|
|
|
|
## Commands and output
|
|
|
|
| Command | Behavior |
|
|
|---|---|
|
|
| `add SOURCE [CONFIG] [--calibration PATH]` | Prepare one source while output is stopped; reply `OK added ID`. Config/calibration apply only to this sensor. |
|
|
| `load SETUP.json` | Add the sources and calibration mappings in a setup file while stopped; reply `OK loaded ID ...`. |
|
|
| `start` | Begin continuous output for all added sensors; requires at least one sensor. Reply `OK start`. |
|
|
| `stop` | Pause continuous output for the whole set; keep all cameras open. Reply `OK stop`. |
|
|
| `read` | Publish one complete processing round; requires a sensor and preserves streaming state on success. |
|
|
| `quit` | Reply `OK quit`, close all cameras and UART, then exit. |
|
|
|
|
To extend the camera set after streaming has started, pause before adding:
|
|
|
|
```text
|
|
stop
|
|
OK stop
|
|
add /dev/video4
|
|
OK added 3
|
|
start
|
|
OK start
|
|
```
|
|
|
|
`add` while streaming replies `ERR add stop streaming first` and opens no source.
|
|
A fifth source or duplicate source is rejected. Removing/replacing cameras requires
|
|
quitting and starting a fresh service. `start`, `stop`, `read` and `quit` take no
|
|
arguments and always act on the full set. The older protocol commands remain removed.
|
|
|
|
Commands are case-insensitive UTF-8 lines terminated by LF, CR or CRLF. Partial
|
|
lines survive read timeouts. Lines exceeding 1024 bytes are discarded through
|
|
their terminator. Quote source/config paths containing spaces:
|
|
|
|
```text
|
|
add "/path/test clip.mp4" "/path/my config.json"
|
|
```
|
|
|
|
Every measurement has five CSV fields, even with only one sensor:
|
|
`force,sensor_id,FNORMAL,FSHEARX,FSHEARY`. Axes follow the SDK; units depend on
|
|
calibration and must not be assumed to be Newtons. CSV carries no units or
|
|
timestamp. The receiver can remain passive after sending setup commands and
|
|
`start`; it needs no further requests to receive continuous data. Filter `force,`
|
|
lines to distinguish measurements from replies and errors.
|
|
|
|
Frames are processed sequentially, not synchronized across cameras. All sources
|
|
must succeed before a processing round is published. A capture/processing failure
|
|
produces `ERR read sensor ID: ...` and stops continuous output for the full set,
|
|
without fabricating zero values or transmitting a partial processing round.
|
|
A transport failure can still interrupt transmission between lines. `start`
|
|
retries processing; restart the service to reopen an unavailable camera.
|
|
|
|
For recorded files, `--no-loop-video` replies `OK eof sensor ID: video ended` and
|
|
pauses the whole set at EOF. Otherwise one rewind and tracker reset is attempted
|
|
per read. Ctrl-C in the login shell ends the service and releases resources.
|
|
|
|
## Callable acquisition API
|
|
|
|
`serial/finger_api.py` has no UART dependency and opens no resources on import.
|
|
Place its directory on the caller's module search path. Adding sources is explicit:
|
|
|
|
```python
|
|
from finger_api import FingerSensorBank
|
|
|
|
bank = FingerSensorBank(config="finger")
|
|
try:
|
|
first_id = bank.add(0, cal_path="/home/radxa/calibrations/finger/DD02-14.json")
|
|
second_id = bank.add(2, config="finger")
|
|
for reading in bank.read_all():
|
|
print(reading.sensor_id, reading.normal, reading.shear_x, reading.shear_y, reading.units)
|
|
finally:
|
|
bank.close()
|
|
```
|
|
|
|
One thread owns the bank. `add()` returns a 1-based ID only after successful
|
|
preparation; it raises on failure and preserves previously added runtimes.
|
|
`read_all()` requires at least one source and returns a tuple only when all
|
|
sources succeed. File EOF raises `EOFError`; capture/processing failure raises
|
|
`RuntimeError`. Each reading contains its own unrolled image, three scalar forces
|
|
and SDK units; older SDKs without a units property report `unknown`. `close()`
|
|
attempts every runtime and clears the camera set. The API caller must pause its
|
|
own processing loop before adding; the UART service enforces this for commands.
|
|
`bank.add_setup("sensors.json")` uses the same transactional batch loader as the
|
|
CLI and UART. `bank.calibration_paths` records explicit calibration paths by ID.
|
|
|
|
## Backend evidence and remaining limits
|
|
|
|
The SDK's `FingerRuntime.open()` creates separate capture, unwarping and sensor
|
|
state for each source. SDK code is unchanged. Verification on 2026-10-14 used
|
|
local SDK revision `3953747f1726b197a3f327a38c65d9878e333e12`: 1, 2, 3 and 4
|
|
recorded sources were added incrementally, with complete readings after each
|
|
addition and three final rounds for each count. Existing runtime identities were
|
|
preserved; capture handles and sensor objects were distinct, and optical-flow
|
|
arrays did not share memory. Resources were released after each case.
|
|
The explicit `DD02-14.json` calibration was also tested on 1-4 recorded sources:
|
|
each instance loaded its assigned file and reported three calibrated `N` axes.
|
|
Four-source JSON loading passed, and invalid explicit calibration was rejected
|
|
without altering an existing sensor. This validates software binding, not physical accuracy.
|
|
|
|
To rerun with a recording containing at least 12 frames, put generated clips and
|
|
caches in an isolated task scratch directory:
|
|
|
|
```bash
|
|
python tests/check_backend.py --recording /path/to/recording.avi --calibration /path/to/DD02-14.json --scratch .scratch/uart-calibration-setup/backend-run
|
|
python -m unittest discover -s tests -v
|
|
```
|
|
|
|
Unit tests separately verify empty startup, explicit additions, failure isolation,
|
|
IDs/limits, stop-before-add, command framing, complete-round output and cleanup.
|
|
The shipped compiled ARM `orisys 0.5.0` wheel and Q6A physical camera/UART setup
|
|
remain unverified. Run the backend check inside the board's installed environment
|
|
to verify that SDK. USB bandwidth, sustained frame rates and command latency
|
|
require hardware validation. Camera opening/warmup and synchronous reads can delay
|
|
command handling. Serial writes have a configurable timeout, default 1 second.
|
|
At 115200 baud/8N1, all data and replies share 11,520 bytes/s.
|