diff --git a/docs/05-core-features/battery.mdx b/docs/05-core-features/battery.mdx index fa8500a..f90b3ab 100644 --- a/docs/05-core-features/battery.mdx +++ b/docs/05-core-features/battery.mdx @@ -38,6 +38,23 @@ Enable the `VBAT` feature to enable the measurement of the battery voltage and t `vbat_scale` - Adjust this setting to match actual measured battery voltage to reported value. Increasing this value increases the measured voltage. +### Voltage Sensor Source + +INAV can read the battery voltage from the flight controller's own ADC, or from a remote source (ESC telemetry, SmartPort, CRSF, or a DroneCAN battery monitor). +Select the source with the `vbat_meter_type` setting: + +| Value | Sensor Source | +| ----- | ---------------------- | +| 0 | None | +| 1 | ADC / hardware sensor | +| 2 | ESC telemetry | +| 3 | Fake (test/development) | +| 4 | SmartPort telemetry | +| 5 | CRSF telemetry | +| 6 | DroneCAN | + +For a DroneCAN battery monitor, set `vbat_meter_type = CAN`; for setup and supported hardware see [Battery Monitoring via DroneCAN](#battery-monitoring-via-dronecan). + ### Voltage Measurement Source Two voltage sources are available: raw voltage and sag compensated voltage. @@ -46,7 +63,7 @@ When the current drawn from a battery varies the provided voltage also varies du The sag can often trigger the battery alarms before the battery is empty and if you are relying on the battery voltage to know the charge state of your battery you have to land or cut the throttle to know the real, without load, battery voltage. The sag compensation algorithm simulates a battery with zero internal resistance and provides a stable reading independent from the drawn current. -You can select the voltage source used for battery alarms and telemetry with the `bat_voltage_source` setting. +You can select the voltage source used for battery alarms and telemetry with the `bat_voltage_src` setting. It can be set to either `RAW` for using raw battery voltage or `SAG_COMP` for using the calculated sag compensated voltage. You can see an illustration of the sag compensation algorithm in action in the following graph: @@ -99,13 +116,18 @@ Enable current monitoring using the CLI command: feature CURRENT_METER ``` -Configure the current meter type using the `current_meter_type` settings here: +Configure the current meter type using the `current_meter_type` setting: | Value | Sensor Type | | ----- | ---------------------- | | 0 | None | -| 1 | ADC/hardware sensor | +| 1 | ADC / hardware sensor | | 2 | Virtual sensor | +| 3 | Fake (test/development) | +| 4 | ESC telemetry | +| 5 | SmartPort telemetry | +| 6 | CRSF telemetry | +| 7 | DroneCAN | Configure capacity using the `battery_capacity` setting, in mAh units. @@ -182,6 +204,25 @@ current_meter_scale = (reported_draw_mAh / charging_data_mAh) * old_current_mete = 435 ``` +## Battery Monitoring via DroneCAN + +A DroneCAN battery monitor sends voltage and current together in a single `BatteryInfo` message. +Both readings come from the same source, so they update in lockstep when using a DroneCAN source. + +Enable voltage and current from a DroneCAN battery monitor: + +``` +set vbat_meter_type = CAN +set current_meter_type = CAN +feature CURRENT_METER +save +``` + +The `CAN` value for both settings is selected from the enumerations documented above: `vbat_meter_type` accepts the sensor-source values listed in the [Voltage Sensor Source](#voltage-sensor-source) table (None, ADC, ESC, Fake, SmartPort, CRSF, DroneCAN); `current_meter_type` accepts the full set in the table above (None, ADC, Virtual, Fake, ESC, SmartPort, CRSF, DroneCAN). +The separate `bat_voltage_src` setting (`RAW` or `SAG_COMP`) controls whether raw or sag-compensated readings are used for battery alarms and telemetry; it is documented under [Voltage Measurement Source](#voltage-measurement-source). + +For general DroneCAN setup (bus bitrate, FC node ID, supported hardware) see [DroneCAN](../06-advanced-features/dronecan.mdx). + ## Power and Current Limiting INAV includes an advanced power and current limiting system to protect your battery and ESCs from excessive discharge rates. diff --git a/docs/05-core-features/gps.mdx b/docs/05-core-features/gps.mdx index aa189da..ac3490a 100644 --- a/docs/05-core-features/gps.mdx +++ b/docs/05-core-features/gps.mdx @@ -257,6 +257,33 @@ If you are using your FC onboard mag, try to place the the FC as far away as pos The current draw can cause the Spektrum receiver to brownout. Instead use a 3.3V regulator and power the GPS from the BEC or separate battery. +## GNSS via DroneCAN + +A DroneCAN GNSS receiver broadcasts position data on the CAN bus, separate from any UART-connected GPS. +You can use a DroneCAN GNSS in place of a Ublox receiver on a serial port. + +To use a DroneCAN GNSS receiver as the position source: + +``` +set gps_provider = DRONECAN +save +``` + +The flight controller will automatically receive GPS data from any DroneCAN GNSS device on the bus. +The GNSS node's own parameters — including which constellations it tracks — live on the node, not in INAV's settings. +Edit them through the **DroneCAN** tab in INAV Configurator: use GetNodeInfo to find the GNSS node, then GetSet to browse and edit its parameters. +Out-of-range writes are rejected in the UI before they're sent. + +The most common firmware on DroneCAN GNSS nodes is AP_Periph. +For the parameter names it exposes (e.g. `GPS_TYPE`, the `GPS_` group, the `GNSS_` group), see the [ArduPilot AP_Periph Complete Parameter List](https://ardupilot.org/dev/docs/AP_Periph-Parameters.html). + +:::info +INAV only supports a single GNSS source at a time. +If a DroneCAN GNSS is selected via `gps_provider = DRONECAN`, the serial-port `GPS` configuration is ignored — including `gps_auto_baud` and `gps_auto_config`, which only apply when `gps_provider` is set to a serial source. +::: + +For general DroneCAN setup (bus bitrate, FC node ID, supported hardware) see [DroneCAN](../06-advanced-features/dronecan.mdx). + ## Related Topics - [GPS Fix Estimation](../06-advanced-features/gps-fix-estimation.mdx) \ No newline at end of file diff --git a/docs/06-advanced-features/dronecan.mdx b/docs/06-advanced-features/dronecan.mdx new file mode 100644 index 0000000..bb91fac --- /dev/null +++ b/docs/06-advanced-features/dronecan.mdx @@ -0,0 +1,143 @@ +--- +title: DroneCAN +description: Connect external sensors and peripherals to INAV over a CAN bus using the DroneCAN protocol +--- + +DroneCAN (formerly UAVCAN v0) is a lightweight protocol designed for reliable communication in aerospace and robotic applications over a CAN bus. +INAV supports DroneCAN for connecting external sensors and peripherals such as battery monitors and GNSS receivers. + +:::info +This page describes the INAV 10.0 (and later) DroneCAN implementation. +DroneCAN sensor support is not present in the currently shipped 9.x firmware — the getting-started [Hardware Overview](../03-getting-started/01-hardware-overview.mdx) still describes 9.x as not supporting DroneCAN sensors, which is correct for 9.x but stale for 10.0. +That page is being updated separately; once the upstream fix lands, this qualification can be removed. +::: + +## What DroneCAN gives you + +A single CAN bus can carry multiple sensors and actuators to and from the flight controller. +Peripherals broadcast on the bus, the flight controller listens, and configuration goes back the other way. +This lets you: + +- Replace a flight-controller ADC with a digital battery monitor that already measures both voltage and current, including per-cell data +- Use a remote GNSS receiver mounted away from RF noise without running a long serial cable +- Add and remove peripherals without re-flashing or re-wiring the FC + +:::info +DroneCAN is independent of your serial-port configuration. +It uses the CAN bus peripheral on the flight controller, which is separate from any UART. +::: + +## Supported hardware + +DroneCAN requires a flight controller with CAN bus hardware: + +- STM32H7 boards (FDCAN peripheral) +- STM32F7 boards (bxCAN peripheral) + +Check your flight controller's documentation to confirm CAN bus availability before connecting any DroneCAN peripherals. + +## Supported features + +| Feature | Status | Notes | +| --- | --- | --- | +| GNSS receiver | Supported | Set `gps_provider = DRONECAN` | +| Battery voltage | Supported | Set `vbat_meter_type = CAN` | +| Battery current | Supported | Set `current_meter_type = CAN` | +| Per-node parameter Get/Set, Restart, Save | Supported | Configurator "DroneCAN" tab — requires INAV 10.0 or later | +| Dynamic Node Allocation (DNA) | Supported | Optional server; assigns node IDs automatically — requires INAV 10.0 or later | +| CAN bus-off event logging | Supported | New blackbox field `droneCANBusOffCount` — requires INAV 10.0 or later | +| ESC / actuator / RC-input over CAN | Not yet | Targeted for a future INAV release | + +## Basic configuration + +Open the **DroneCAN** tab in INAV Configurator to configure the flight controller on the bus — node ID, bitrate, and the DNA server toggle all live there. +The same settings are also available via the CLI, which is useful for scripted setup or if the tab isn't available on your platform. + +``` +set dronecan_node_id = 10 +set dronecan_bitrate = 1000KBPS +save +``` + +| Setting | Values | Default | Description | +| --- | --- | --- | --- | +| `dronecan_node_id` | 1-127 | 10 | CAN node ID for the flight controller | +| `dronecan_bitrate` | 125KBPS, 250KBPS, 500KBPS, 1000KBPS | 1000KBPS | CAN bus bitrate; all peripherals must match | +| `dronecan_use_dna_server` | OFF, ON | ON | Whether the flight controller runs the Dynamic Node Allocation server (see [Node management](#node-management)) | + +:::note +Node IDs 126 and 127 are reserved for network maintenance tools — avoid assigning them to your FC or peripherals. +::: + +### Common next steps + +After enabling DroneCAN on the bus, choose where each sensor's data should come from: + +- For a DroneCAN GNSS receiver, see the [GPS](../05-core-features/gps.mdx) page. +- For a DroneCAN battery monitor (voltage and/or current), see the [Battery Monitoring](../05-core-features/battery.mdx) page. + +## Node management + +:::info +This section describes behaviour available in INAV 10.0 and later, behind firmware PR #11683 and configurator PR #2671 (parameter Get/Set and the DroneCAN configurator tab), firmware PR #11688 and configurator PR #2672 (Dynamic Node Allocation), and firmware PR #11729 (CAN bus-off blackbox logging). +It documents the *intended* user experience; behaviour may shift during review before these PRs merge. +::: + +INAV exposes DroneCAN nodes it can see on the bus through the INAV Configurator's **DroneCAN** tab. +For each node you can: + +- Read its identity (`GetNodeInfo`) — name, hardware/software version, unique ID +- Browse and edit its parameters (`GetSet`) — with the per-parameter `min`/`max` reported by the node itself, so out-of-range writes are rejected in the UI before they're sent +- Save parameters to the node's EEPROM (`ExecuteOpcode(SAVE)`) +- Restart the node (`RestartNode`) — useful after firmware updates or when a peripheral is wedged + +:::warning +The **Restart** button on a node restarts *that node*, not the flight controller. +It is intentionally placed away from the global **Save & Reboot** button so the two cannot be confused. +::: + +### Per-node restart caveat + +Some peripherals acknowledge a `RestartNode` command and then reset themselves so quickly that their ACK frame never makes it onto the bus before the bus is gone. +In that case the configurator will report "RestartNode failed" even though the node did in fact restart successfully. +Confirm a successful restart by checking the node's `NodeStatus` heartbeats on the bus before assuming the restart was lost. + +### Dynamic Node Allocation + +If you enable the DNA server (`dronecan_use_dna_server = ON`, the default), the flight controller assigns node IDs to peripherals that don't already have one configured. +This means you can plug in a new DroneCAN peripheral and not have to manually configure its node ID first. + +The DNA server: + +- Honours a peripheral's preferred node ID where it can (within the available range, skipping already-allocated IDs) +- Stores its allocation table in persistent storage so the same peripheral gets the same node ID across power cycles +- Detects conflicts with actively-broadcasting nodes and reassigns rather than overwriting +- Reserves node IDs 126 and 127 for network maintenance tools and the FC's own ID range + +If you prefer to assign every node ID manually, set `dronecan_use_dna_server = OFF` — or uncheck the toggle in the **DroneCAN** tab. + +### Blackbox logging + +INAV exposes a cumulative bus-off event counter as a blackbox slow (S) frame field, `droneCANBusOffCount`. +This lets you diagnose intermittent CAN bus faults from a recorded flight log without having to attach the configurator live and watch the `dronecan` CLI. + +The field is gated behind `USE_DRONECAN` in the firmware and only appears in blackbox logs when DroneCAN is enabled on the target. + +## Bus wiring notes + +DroneCAN requires a properly terminated CAN bus — termination at each physical end of the bus, not in the middle. + +- Each flight controller and each peripheral should declare its own bus termination state in its documentation; verify both ends of the bus are terminated. +- A common cause of intermittent DroneCAN faults is missing or duplicated termination, which shows up in blackbox as an incrementing `droneCANBusOffCount` during the affected segment. +- Avoid running the CAN bus parallel to and close to RF sources (video transmitter, radio receiver with telemetry) — the bus is differential but shares the same physical space and can pick up noise. + +## Troubleshooting + +If a peripheral isn't appearing in the configurator or isn't being seen by INAV: + +- Verify the bitrate matches between the FC and all peripherals — the most common cause is a peripheral left at a different default bitrate from the FC +- Check the CAN wiring: CAN-H and CAN-L must not be swapped, both ends of the bus must be terminated, and the bus should have a common ground +- Check `dronecan` in the CLI for an active node count +- If you suspect bus-off events, decode a blackbox log and look at `droneCANBusOffCount` over time + +For more detail on the protocol internals and the driver layer, see `docs/DroneCAN.md` and `docs/DroneCAN-Driver.md` in the INAV firmware repository. \ No newline at end of file