Getting Started

This guide helps you install, build, and run mag-usb on a typical Linux system.

Prerequisites

  • Linux host with USB 2.0 support

  • CMake 3.22+

  • A C compiler (GCC or Clang)

  • Optional: Microsoft VS Code, VSCodium, or JetBrains CLion for an IDE workflow

  • Pololu Isolated USB-to-I²C Adapter (products 5396 or 5397)

  • RM3100-based magnetometer board

Hardware connection

  1. Connect the Pololu USB-to-I²C adapter to your host via USB.

  2. Wire SDA/SCL/GND (and 5V if required) between the adapter and the sensor board.

  3. On Linux, the adapter typically appears as /dev/ttyACMn. Installing install/99-PololuI2C.rules adds a /dev/ttyMAG0 symlink that resolves to whichever ACM device the adapter enumerated as — this is the path the program uses by default.

For details and udev rules to stabilize the device path, see docs/Hardware-Setup.md.

Build

You can build using CLion or plain CMake.

CLion:

  • Open the project folder.

  • Select the Debug or Release profile.

  • Build the target: mag-usb

Command line (Release example):

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --target mag-usb

Quick run

./build/mag-usb -Q                    # default device: /dev/ttyMAG0
./build/mag-usb -O /dev/ttyACM0 -Q    # explicit override

Flags:

  • -O sets the Pololu device path.

  • -Q checks adapter presence/availability.

Print current settings (and exit):

./build/mag-usb -P

The program searches for config.toml in /etc/mag-usb/ first, then in the local directory. If neither is found, internal defaults are used.

Named Pipes (Optional)

To enable named pipe output for local monitoring:

./build/mag-usb -u

You can specify custom pipe paths with -i and -o. Defaults are in /var/run/.

WebSocket Output (Optional)

Enable WebSocket support at build time:

cmake -S . -B build -DENABLE_WEBSOCKET=ON
cmake --build build --target mag-usb

Then enable it at runtime:

./build/mag-usb -W -w 8765 -a 0.0.0.0

Or set the [websocket] section in config.toml.

For manual testing, build and run the ws-client tool:

cmake --build build --target ws-client
./build/ws-client 127.0.0.1 8765 /

Run with help:

./mag-usb -h

Tests (optional)

Enable and run unit tests:

cmake -S . -B build -DBUILD_TESTING=ON
cmake --build build --target i2c-pololu-tests
(cd build && ctest --output-on-failure)

Next steps

  • Review README.md (command-line help section) and docs/Configuration.md for available flags and configuration keys.

  • If you use the adapter regularly, consider installing the provided udev rule (install/99-PololuI2C.rules) to get stable permissions and device naming.