Skip to content

update docs #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
towynlin merged 1 commit into from
Apr 3, 2026
Merged

update docs #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
104 changes: 87 additions & 17 deletions docs/operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,66 @@
## CLI reference

```
bm_sbc_<app> --node-id <hex64> [--peer <hex64>]... [--socket-dir <path>]
[--uart <device>] [--baud <rate>]
bm_sbc_<app> --init <toml> [overrides...]
bm_sbc_<app> --node-id <hex64> [options...]
```

| Flag | Required | Default | Description |
|----------------|----------|------------|------------------------------------------|
| `--node-id` | yes | | 64-bit node ID in hex (e.g. `0x0001`) |
| `--peer` | no | | Peer node ID. Repeat for each peer. |
| `--socket-dir` | no | `/tmp` | Directory for Unix domain sockets. |
| `--uart` | no | | Serial device path. Enables gateway mode.|
| `--baud` | no | `115200` | UART baud rate. |
Full option list:

```
bm_sbc_<app> --node-id <hex64> [--init <toml>] [--cfg-dir <path>]
[--peer <hex64>]... [--socket-dir <path>]
[--uart <device>] [--baud <rate>] [--pcap <path>]
[--log-dir <path>] [--log-level <level>] [--log-stdout]
```

| Flag | Required | Default | Description |
|-----------------|----------|----------------------|-------------------------------------------------------|
| `--init` | no | | TOML init file; provides all settings below. |
| `--node-id` | yes* | | 64-bit node ID in hex (e.g. `0x0001`). *Required if not set by `--init`. |
| `--cfg-dir` | no | | Directory for config partition files. |
| `--peer` | no | | Peer node ID. Repeat for each peer. |
| `--socket-dir` | no | `/tmp` | Directory for Unix domain sockets. |
| `--uart` | no | | Serial device path. Enables gateway mode. |
| `--baud` | no | `115200` | UART baud rate. |
| `--pcap` | no | | Write captured L2 frames to a pcap file. |
| `--log-dir` | no | `/var/log/bm_sbc` | Directory for log files. |
| `--log-level` | no | `info` | Minimum log level: `trace`/`debug`/`info`/`warn`/`error`/`fatal`. |
| `--log-stdout` | no | false (true if TTY) | Also write logs to stdout. |

CLI flags override values from the init file. The init file is loaded first; any flag supplied on the command line takes precedence.

## Init file (TOML)

All settings can be provided via a TOML file passed with `--init`. Example files are in `examples/`. TOML keys mirror the CLI flag names (hyphens preserved):

```toml
node-id = "0x0000000000000001"
cfg-dir = "/tmp/bm_node1"
socket-dir = "/tmp"
peers = ["0x0000000000000002"]

# UART gateway (optional)
# uart-device = "/dev/ttyUSB0"
# uart-baud = 115200

# Logging (all optional)
# log-dir = "/var/log/bm_sbc"
# log-level = "info"
# log-stdout = false
```

See `examples/node1.toml` and `examples/node2.toml` for working examples.

## Environment variables

Log settings can also be seeded from environment variables. CLI flags and TOML values override them.

| Variable | Description |
|-----------------------|----------------------------------------------------------|
| `BM_SBC_LOG_DIR` | Log file directory (same as `--log-dir`). |
| `BM_SBC_LOG_LEVEL` | Minimum log level name (same as `--log-level`). |
| `BM_SBC_LOG_STDOUT` | Set to `1` to tee logs to stdout (same as `--log-stdout`).|

## Modes

Expand All @@ -27,18 +76,18 @@ peers and the UART link transparently.

## Topology

Topology is static and fully specified at launch via `--peer` flags.
There is no dynamic peer discovery between processes.
Topology is static and fully specified at launch via `--peer` flags (or
`peers` in the init file). There is no dynamic peer discovery between
processes.

Each process binds a socket at:
```
<socket-dir>/bm_sbc_<node_id_hex16>.sock
```

Two processes are neighbors if and only if each lists the other as a `--peer`.
Two processes are neighbors if and only if each lists the other as a peer.

Port assignment is deterministic: the Nth `--peer` flag maps to virtual
port N.
Port assignment is deterministic: the Nth peer maps to virtual port N.

## Limits

Expand All @@ -49,10 +98,31 @@ port N.
| Socket path length | 108 | `sun_path` limit; socket-dir must be short|
| Max L2 frame | 1514 | 14-byte Ethernet header + 1500-byte MTU |

## Logging

Log output is written to a per-process file:
```
<log-dir>/<app_name>_<node_id_hex16>.log
```

Default directory: `/var/log/bm_sbc`. If the directory cannot be created or
the file cannot be opened, the process falls back to stdout-only and prints a
warning to stderr.

Log line format:
```
2024-01-15T12:34:56.789012Z INFO [multinode node=0x0000000000000001] stack initialized
```

**Log rotation**: send `SIGHUP` to reopen the log file. Useful with
`logrotate`.

When stdout is a TTY (interactive shell), logs are also written to stdout
automatically. Use `--log-stdout` to force this in non-TTY contexts.

## Diagnostics

All output goes to stdout via `bm_debug()` (which is `printf`). Key
strings to grep for:
Key patterns to search for in log output:

| Pattern | Meaning |
|--------------------------------------|--------------------------------------|
Expand All @@ -65,11 +135,11 @@ strings to grep for:
| `vpd: peer count N exceeds cap 15` | Peer list was truncated |
| `UART transport init failed` | Serial port open/config failed |
| `err: N at <file>:<line>` | bm_core internal error |
| `pcap capture ->` | pcap capture is active |

## Stopping

Send SIGTERM or SIGINT. There is no graceful shutdown sequence; the
process exits and the OS cleans up sockets and file descriptors.

<!-- TODO: Add graceful shutdown if needed in the future. -->

10 changes: 9 additions & 1 deletion docs/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,13 +39,21 @@ Start a node:
./build/bm_sbc_example --node-id 0x0000000000000001
```

Start two connected nodes:
Start two connected nodes using TOML init files (recommended):
```
./build/bm_sbc_multinode --init examples/node1.toml &
./build/bm_sbc_multinode --init examples/node2.toml &
```

Or pass flags directly:
```
./build/bm_sbc_multinode --node-id 0x0001 --peer 0x0002 &
./build/bm_sbc_multinode --node-id 0x0002 --peer 0x0001 &
```

Both nodes will discover each other, exchange pings, and log pub/sub traffic.
Logs are written to `/var/log/bm_sbc/` by default; add `--log-stdout` to also
print to the terminal.

## Run the tests

Expand Down
13 changes: 13 additions & 0 deletions docs/uart-gateway.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ on the gateway process's network device. Frames pass through transparently

## Usage

Via CLI flags:
```
./build/bm_sbc_multinode \
--node-id 0x0000000000000001 \
Expand All @@ -17,6 +18,18 @@ on the gateway process's network device. Frames pass through transparently
--baud 115200
```

Or via a TOML init file:
```toml
node-id = "0x0000000000000001"
socket-dir = "/tmp"
peers = ["0x0000000000000002"]
uart-device = "/dev/ttyUSB0"
uart-baud = 115200
```
```
./build/bm_sbc_multinode --init gateway.toml
```

This creates a gateway with:
- Virtual port 1: local peer `0x0002`
- Virtual port 2: UART link
Expand Down
Loading