Skip to content

Commit 2dce5a4

Browse files
mairasclaude
andcommitted
docs: add GNSS HAT section to interfaces guide
Document the optional Max-M8Q GNSS HAT: auto-configuration service, data access via gpsd, late installation procedure, and non-HaLOS setup instructions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 541d581 commit 2dce5a4

1 file changed

Lines changed: 60 additions & 0 deletions

File tree

docs/user-guide/interfaces.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,66 @@ The high-speed capability of the interface also supports non-standard applicatio
9595
- **Troubleshooting:** See [Troubleshooting Guide](./troubleshooting.md)
9696

9797

98+
## GNSS (GPS)
99+
100+
HALPI2 supports GNSS receiver HATs connected to UART0 (`/dev/ttyAMA0`). Any GNSS receiver on this port will work with gpsd out of the box.
101+
102+
For u-blox receivers (such as the Max-M8Q), HaLOS Marine images additionally provide automatic configuration optimized for marine use.
103+
104+
### Auto-Configuration (u-blox receivers)
105+
106+
On HaLOS Marine images, a systemd service (`configure-gnss-marine`) automatically detects and configures u-blox receivers on first boot:
107+
108+
| Parameter | Value |
109+
|:----------|:------|
110+
| Baud rate | 115200 bps (factory default: 9600) |
111+
| Update rate | 10 Hz (100 ms) |
112+
| Dynamic model | Sea (optimized for marine use) |
113+
114+
The configuration is saved to the receiver's flash memory, so it persists across power cycles.
115+
116+
The auto-configuration service probes for the receiver on up to three consecutive boots. If no receiver is detected after three attempts, the service stops retrying. This accommodates manufacturing and testing workflows where the HAT may not be attached during initial device setup.
117+
118+
### Late Installation
119+
120+
If the GNSS HAT is installed after the auto-configuration window has passed, reset the service manually:
121+
122+
```bash
123+
sudo rm -f /var/lib/halos/gnss-marine-configured /var/lib/halos/gnss-marine-attempts
124+
sudo reboot
125+
```
126+
127+
The service will run again on the next boot and configure the receiver.
128+
129+
### Data Access
130+
131+
GPS data is provided by [gpsd](https://gpsd.io/) on TCP port 2947. On HaLOS Marine images, Signal K connects to gpsd automatically — no additional configuration is needed.
132+
133+
For diagnostics, use the standard gpsd command-line tools:
134+
135+
```bash
136+
# Monitor GPS data in real-time
137+
gpsmon
138+
139+
# Output raw NMEA 0183 sentences
140+
gpspipe -r
141+
```
142+
143+
### Non-HaLOS Images
144+
145+
On Raspberry Pi OS or other operating systems, install and configure gpsd manually:
146+
147+
```bash
148+
sudo apt install gpsd gpsd-clients
149+
```
150+
151+
Edit `/etc/default/gpsd` to set `DEVICES="/dev/ttyAMA0"` and restart the service. The receiver will operate at its factory default settings (9600 baud, 1 Hz) unless configured with `ubxtool` from the `gpsd-clients` package.
152+
153+
!!! quote "Related Information"
154+
- **gpsd on HaLOS:** See [HaLOS GPS documentation](https://docs.halos.fi/user-guide/gps/)
155+
- **Software setup:** See [Software Guide](./software.md)
156+
157+
98158
## Ethernet
99159

100160
HALPI2 includes a Gigabit Ethernet interface that provides high-speed network connectivity for data transfer, remote access, and integration with onboard networks. The ethernet port on the carrier board is a standard RJ45 connector. It is broken out to a panel connector that can be connected to an external Ethernet cable.

0 commit comments

Comments
 (0)