# mag-usb Requirements

This document defines the functional, non-functional, and delivery requirements for a clean-room reimplementation of the mag-usb project.
It is a specification document, not an implementation guide.
It is intended as a start-to-finish blueprint: hardware, software, build, runtime behavior, and documentation.

## 1. Scope and goals
- Provide a Linux command-line utility that reads a PNI RM3100 3-axis magnetometer via a Pololu USB-to-I2C adapter.
- Emit time-stamped magnetic field vectors in a JSON-lines format for downstream ingestion.
- Support a simple TOML configuration file, with command-line overrides.
- Provide lightweight diagnostics (adapter check, I2C bus scan, sensor presence checks).
- Keep implementation portable C (C11) with minimal dependencies.

Non-goals:
- Windows support.
- Arbitrary-angle orientation or full magnetometer calibration (soft/hard iron compensation).
- GUI or web interface.

## 2. Supported platforms and environment
- Target OS: Linux.
- Expected device nodes: USB CDC ACM (`/dev/ttyACM*`).
- macOS: untested and optional.
- SBCs (Raspberry Pi class): not primary target; use Pololu adapter instead of native GPIO/I2C libraries.

## 3. Hardware requirements
- Pololu Isolated USB-to-I2C Adapter:
  - Product 5396 or 5397.
- RM3100-based magnetometer board.
- Wiring:
  - SDA to SDA, SCL to SCL, GND to GND, optional +5V if required by board.
  - Confirm I2C pull-ups exist.
- Optional: MCP9808 temperature sensor for remote temperature readings.

## 4. System behavior and functional requirements

### 4.1 Program startup
- Load defaults for all parameters.
- Load configuration file from:
  1) `/etc/mag-usb/config.toml`
  2) `config.toml` in current working directory
- If the first file fails to load or does not exist, fall back to local file.
- Ignore or clamp invalid config values to defaults.
- Parse command-line arguments after config load; CLI overrides config and defaults.
- If `-P` is passed, print active settings and exit before hardware initialization.

### 4.2 Command-line interface (CLI)
Provide the following options:
- `-B <reg mask>`: BIST (not implemented, but option exists).
- `-C`: read back cycle count registers before sampling.
- `-c <count>`: set cycle count for X/Y/Z; valid range 1..800 (decimal).
- `-D <rate>`: set CMM sample rate (integer).
- `-g <mode>`: sampling mode (POLL=0, CMM=1).
- `-O <path>`: Pololu adapter device path (default `/dev/ttyACM0`).
- `-P`: show current settings and exit.
- `-Q`: verify Pololu adapter presence and exit.
- `-M`: verify magnetometer presence and version and exit.
- `-S`: scan I2C bus and exit.
- `-T`: verify temperature sensor presence and version and exit.
- `-u`: enable named pipes for output.
- `-i <path>`: input named pipe path.
- `-o <path>`: output named pipe path.
- `-V`: print version and exit.
- `-h`/`-?`: print help and exit.

### 4.3 I2C adapter handling
- Verify adapter availability at the configured device path with timeout.
- Validate adapter is a supported Pololu device.
- If adapter is missing or invalid, exit with a clear error.
- If `-Q` is set, only validate adapter and exit 0/1.

### 4.4 Sensor handling
- Support RM3100 magnetometer at a configurable I2C address (default from build config).
- Support MCP9808 temperature sensor at configurable I2C address (default 0x1F).
- Provide diagnostic checks:
  - `-M`: verify magnetometer.
  - `-T`: verify temperature sensor.
  - `-S`: scan I2C bus and report devices.
- Initialize magnetometer registers before sampling.

### 4.5 Sampling and output
- Primary data output: JSON lines, one per sample.
- Output schema:
  - `ts` (string): UTC timestamp, format `DD Mon YYYY HH:MM:SS` (RFC-2822-like without timezone).
  - `rt` (number): remote temperature in deg C.
  - `x`, `y`, `z` (number): magnetometer values in nT, formatted with 3 decimal places.
- Convert RM3100 raw counts to microTesla then multiply by 1000 to nT.
- Apply orientation rotations (see 4.6) before output.
- Log and diagnostic messages may be interleaved with JSON lines on the same stream.

### 4.6 Orientation rotations
- Support 90-degree increments about X, Y, Z axes using right-hand rule.
- Allowed values: -180, -90, 0, 90, 180.
- Apply rotations in order X, then Y, then Z.
- Invalid values fall back to 0.

### 4.7 Named pipes and logging
- If `use_pipes` is enabled or `-u` flag is provided:
  - Create FIFOs if missing with mode 0666.
  - Default paths (from sample config):
    - Input: `/run/mag-usb/magctl.fifo`
    - Output: `/run/mag-usb/magdata.fifo`
  - Open output pipe as non-blocking write, input as non-blocking read.
- If `write_logs` is enabled:
  - Write JSON lines to log files in `log_output_path`.
  - Create directory if `create_log_path_if_empty` is true.

### 4.8 WebSocket output (optional)
- Provide a build flag `ENABLE_WEBSOCKET` to include WebSocket server support.
- When enabled and configured, broadcast each JSON output line to all connected clients.
- Allow runtime configuration of bind address and port.
- Accept multiple concurrent clients; send text frames.

### 4.9 Configuration keys
TOML sections and keys to support:

[node_information]
- `maintainer` (string)
- `maintainer_email` (string)

[node_location]
- `latitude` (string)
- `longitude` (string)
- `elevation` (string)
- `grid_square` (string)

[i2c]
- `use_I2C_converter` (bool)
- `portpath` (string)
- `bus_number` (int)
- `scan_bus` (bool)

[magnetometer]
- `address` (int, decimal or hex)
- `cc_x`, `cc_y`, `cc_z` (int)
- `gain_x`, `gain_y`, `gain_z` (double)
- `tmrc_rate` (int, decimal or hex)
- `nos_reg_value` (int)
- `drdy_delay` (int)
- `sampling_mode` (string "POLL" or "CMM")
- `cmm_sample_rate` (int)
- `readback_cc_regs` (bool)

[mag_orientation]
- `mag_translate_x`, `mag_translate_y`, `mag_translate_z` (int)

[temperature]
- `remote_temp_address` (int, decimal or hex)

[output]
- `write_logs` (bool)
- `log_output_path` (string)
- `create_log_path_if_empty` (bool)
- `use_pipes` (bool)
- `pipe_in_path` (string)
- `pipe_out_path` (string)

[websocket]
- `enable` (bool)
- `bind_address` (string)
- `port` (int)

## 5. Non-functional requirements
- Language: C11; avoid compiler-specific extensions without guards.
- Dependencies: none beyond standard POSIX/Linux system libraries.
- Build tooling: CMake 3.22+.
- Warnings: build with `-Wall -Wextra -Wpedantic`; allow optional `-Werror`.
- Runtime stability: exit with meaningful error messages for adapter/sensor failures.
- Performance: stable sampling, acknowledging jitter from host scheduling and JSON printing.

## 6. Build, test, and packaging

### 6.1 Build
- Provide a top-level `CMakeLists.txt`.
- Build targets:
  - `mag-usb` (main CLI).
  - `i2c-pololu-tests` (unit tests).
- Provide Debug/Release builds via CMake or IDEs (e.g., CLion).

### 6.2 Tests
- Integrate unit tests with CTest.
- Command line:
  - `cmake -S . -B build -DBUILD_TESTING=ON`
  - `cmake --build build --target i2c-pololu-tests`
  - `(cd build && ctest --output-on-failure)`

### 6.3 Installation artifacts
- Include a sample `config.toml`.
- Provide udev rule for Pololu adapter in `install/99-PololuI2C.rules`.
- Document installation of udev rule and permissions.

## 7. Documentation deliverables
Required documentation pages:
- Getting started and build steps.
- Hardware wiring and udev setup.
- Configuration reference and examples.
- Output data format.
- Orientation and axes explanation.
- Troubleshooting guide.
- Development guide (build matrix and coding patterns).

## 8. Acceptance criteria
- Build succeeds with CMake 3.22+ on Linux using GCC or Clang.
- `mag-usb -h` shows all documented CLI flags.
- `mag-usb -P` prints effective configuration values.
- `mag-usb -Q` validates adapter and exits.
- JSON output matches schema and units, with orientation rotations applied.
- Config file parsing and CLI overrides behave as specified.
- Named pipes and logging operate per configuration with correct permissions.
- Unit tests compile and run via CTest.