# 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.