Configuration

mag-usb reads an optional config.toml at startup. It searches for the configuration file in the following order:

  1. /etc/mag-usb/config.toml

  2. config.toml in the current working directory.

If neither file is found, defaults are used. Invalid values are ignored or reduced to defaults. Command-line arguments always override both default values and those found in any configuration file.

Tip: Run ./mag-usb -P to print the active settings and exit.

File format

  • Syntax: TOML (key = value). Lines beginning with # are comments.

  • Sections use [section_name] headers.

Sections and keys

Below is the complete reference of supported sections/keys, their types, defaults, and notes.

[node_information]

  • maintainer (string)

  • maintainer_email (string)

Defaults: empty strings.

[node_location]

  • latitude (string) — free‑form (e.g., “38.92263”).

  • longitude (string)

  • elevation (string) — free‑form (e.g., “230 m”).

  • grid_square (string) — e.g., “EM38uw”.

Defaults: empty strings.

[i2c]

  • use_I2C_converter (bool) — Use Pololu USB‑to‑I²C adapter. Default: true (when built with USE_POLOLU=TRUE).

  • portpath (string) — Adapter device path. Default: /dev/ttyMAG0 (created by install/99-PololuI2C.rules; falls through to a bare /dev/ttyACM* if the udev rule is not installed and -O is not supplied).

  • bus_number (int) — Linux I²C bus number for non‑Pololu setups. Default: 1.

  • scan_bus (bool) — Probe for devices on startup. Default: false.

Notes:

  • If use_I2C_converter=true, portpath must be accessible to the process (see udev notes in Hardware‑Setup.md).

[magnetometer]

  • address (int, decimal or hex 0xNN) — RM3100 I²C address. Default: build‑time default from RM3100_I2C_ADDRESS.

  • cc_x, cc_y, cc_z (int) — Cycle counts. Typical values: 200, 400. Default: 400 (if set in config.toml).

  • gain_x, gain_y, gain_z (double) — Gains. Default: 150.0.

  • tmrc_rate (int, decimal or hex) — TMRC register value. Default: 0x96.

  • nos_reg_value (int) — Number‑of‑samples register value. Default: 60.

  • drdy_delay (int) — Sleep between DRDY-poll iterations in milliseconds. Default: 10. (The implementation passes drdy_delay * 1000 to usleep(), which takes microseconds; the configured value is therefore an ms count, not a µs count.)

  • sampling_mode (string) — "POLL" or "CMM". Default: "POLL".

  • cmm_sample_rate (int) — CMM sample rate (Hz). Default: 400.

  • readback_cc_regs (bool) — Read back CC registers after setting. Default: false.

[mag_orientation]

Defines fixed 90°‑increment rotations applied to the measured vector before printing.

  • mag_translate_x (int) — Allowed values: -180, -90, 0, 90, 180.

  • mag_translate_y (int) — Allowed values: -180, -90, 0, 90, 180.

  • mag_translate_z (int) — Allowed values: -180, -90, 0, 90, 180.

Rules:

  • Missing/invalid values default to 0.

  • 180 and -180 are treated equivalently.

  • Rotations are applied in the order X, then Y, then Z, using right‑hand rule conventions.

  • See Orientation-and-Axes.md for visuals and examples.

[temperature]

  • remote_temp_address (int, decimal or hex) — MCP9808 temperature sensor address. Default: 0x1F.

[output]

  • write_logs (bool) — Write logs to files. Default: false.

  • log_output_path (string) — Path for log files. Default: ./logs (when logging enabled).

  • create_log_path_if_empty (bool) — Create log_output_path if missing. Default: true.

  • use_pipes (bool) — Use named pipes for IPC. Default: false.

  • pipe_in_path (string) — Path to control pipe (writer side). Default: /run/mag-usb/magctl.fifo.

  • pipe_out_path (string) — Path to data pipe (reader side). Default: /run/mag-usb/magdata.fifo.

Note: When use_pipes=true, the program will create the pipes if they do not exist with 0666 permissions.

[websocket]

  • enable (bool) — Enable the WebSocket output server. Default: false.

  • bind_address (string) — Server bind address. Default: 0.0.0.0.

  • port (int) — Server port. Default: 8765. Note: This section is active only when built with -DENABLE_WEBSOCKET=ON.

Example

# mag-usb Configuration File
# Lines starting with # are comments.
# Inline comments (Data followed by hashmark) not allowed.
[node_information]
maintainer = "Dave Witten, KD0EAG"
maintainer_email = "wittend@wwrinc.com"

[node_location]
# Tools:
#   lat/long: Google Maps or GNSS device.
#   Altitude: Optional, or Use GNSS device, or find yourself in Google Earth and look at the status bar at the bottom.
#   Grid square conversion: https://www.giangrandi.org/electronics/radio/qthloccalc.shtml or similar.
latitude = "38.92263"
longitude = "-92.29831"
elevation = "230 M"
grid_square = "EM38uw"

[output]
# Write logfiles to log_output_path..
write_logs = false
# create logfiles in this location.
log_output_path = "./logs"
# create this location if it does not esist.
create_log_path_if_empty = true

# Use named pipes for IPC.
use_pipes = false
# Pipe paths (if use_pipes is true).
pipe_in_path = "/run/mag-usb/magctl.fifo"
pipe_out_path = "/run/mag-usb/magdata.fifo"

[websocket]
# Enable WebSocket output server.
enable = false
# Bind address and port for WebSocket clients.
bind_address = "0.0.0.0"
port = 8765

[i2c]
# Use external USB to I2C device.
use_I2C_converter = true
# Path to the I2C device.
portpath = "/dev/ttyMAG0"
# I2C bus number (for non-Pololu setups).
bus_number = 1
# Scan I2C bus on startup.
scan_bus = false

[magnetometer]
# Magnetometer I2C address (hex format supported).
address = 0x23
# Cycle Count registers (200 or 400 typically).
cc_x = 400
cc_y = 400
cc_z = 400
# Gain values.
gain_x = 150.0
# TMRC Rate register value (hex format).
tmrc_rate = 0x96
# Number of samples register value.
nos_reg_value = 60
# DRDY delay in milliseconds (passed to usleep as ms * 1000).
drdy_delay = 10
# Sampling mode: "POLL" or "CMM".
sampling_mode = "POLL"
# CMM sample rate (Hz)
cmm_sample_rate = 400
# Read back cycle count registers after setting.
readback_cc_regs = false

# Magnetometer Orientation in degrees relative to default (See hardware setup docs).
# Plus and minus 180 are equivalent. Plus and minus 90 are different!
[mag_orientation]
# Allowed values: -180, -90, 0, 90, 180
mag_translate_x = 0
mag_translate_y = 0
mag_translate_z = 0

[temperature]
# Remote temperature sensor I2C address
remote_temp_address = 0x1F

Configuration Example Fig. 3: Sample config.toml file for mag-usb.