fly316/PX4-Autopilot
7
0
Fork 0
mirror of https://gitee.com/mirrors_PX4/PX4-Autopilot.git synced 2026-10-20 03:33:34 +08:00
Code Issues Packages Projects Releases Wiki Activity

Move PX4 Guide source into /docs (#24490)

Browse Source 
* Add vitepress tree

* Update existing workflows so they dont trigger on changes in the docs path

* Add nojekyll, package.json, LICENCE etc

* Add crowdin docs upload/download scripts

* Add docs flaw checker workflows

* Used docs prefix for docs workflows

* Crowdin obvious fixes

* ci: docs move to self hosted runner

runs on a beefy server for faster builds

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* ci: don't run build action for docs or ci changes

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* ci: update runners

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

* Add docs/en

* Add docs assets and scripts

* Fix up editlinks to point to PX4 sources

* Download just the translations that are supported

* Add translation sources for zh, uk, ko

* Update latest tranlsation and uorb graphs

* update vitepress to latest

---------

Signed-off-by: Ramon Roche <mrpollo@gmail.com>
Co-authored-by: Ramon Roche <mrpollo@gmail.com>
This commit is contained in:
Hamish Willee
2025-03-13 16:08:27 +11:00
committed by GitHub
co-authored by Ramon Roche
parent 8e6d2ebe4a
commit 88d623bedb
5176 changed files with 558771 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/peripherals/adsb_flarm.md
+180
View File
@@ -0,0 +1,180 @@
# ADS-B/FLARM/UTM Receivers: Air Traffic Avoidance
PX4 supports simple air traffic avoidance in [missions](../flying/missions.md) using [ADS-B](https://en.wikipedia.org/wiki/Automatic_dependent_surveillance_%E2%80%93_broadcast), [FLARM](https://en.wikipedia.org/wiki/FLARM), or [UTM](https://www.faa.gov/uas/research_development/traffic_management) transponders that use the standard MAVLink interfaces.
If a potential collision is detected, PX4 can _warn_, immediately [land](../flight_modes_mc/land.md), or [return](../flight_modes_mc/return.md) (depending on the value of [NAV_TRAFF_AVOID](#NAV_TRAFF_AVOID)).
## Supported Hardware
PX4 traffic avoidance works with ADS-B or FLARM products that supply transponder data using the MAVLink [ADSB_VEHICLE](https://mavlink.io/en/messages/common.html#ADSB_VEHICLE) message, and UTM products that supply transponder data using the MAVLink [UTM_GLOBAL_POSITION](https://mavlink.io/en/messages/common.html#UTM_GLOBAL_POSITION) message.
It has been tested with the following devices:
- [PingRX ADS-B Receiver](https://uavionix.com/product/pingrx-pro/) (uAvionix)
- [FLARM](https://flarm.com/products/uav/atom-uav-flarm-for-drones/) <!-- I think originally https://flarm.com/products/powerflarm/uav/ -->
## Hardware Setup
Any of the devices can be connected to any free/unused serial port on the flight controller.
Most commonly they are connected to `TELEM2` (if this is not being use for some other purpose).
### PingRX
The PingRX MAVLink port uses a JST ZHR-4 mating connector with pinout as shown below.
| Pin | Signal | Volt |
| ------- | -------- | ------------ |
| 1 (red) | RX (IN) | +5V tolerant |
| 2 (blk) | TX (OUT) |
| 3 (blk) | Power | +4 to 6V |
| 4 (blk) | GND | GND |
The PingRX comes with connector cable that can be attached directly to the TELEM2 port (DF13-6P) on an [mRo Pixhawk](../flight_controller/mro_pixhawk.md).
For other ports or boards, you will need to obtain your own cable.
## FLARM
FLARM has an on-board DF-13 6 Pin connector that has an identical pinout to the [mRo Pixhawk](../flight_controller/mro_pixhawk.md).
| Pin | Signal | Volt |
| ------- | -------- | ----------- |
| 1 (red) | VCC | +4V to +36V |
| 2 (blk) | TX (OUT) | +3.3V |
| 3 (blk) | RX (IN) | +3.3V |
| 4 (blk) | - | +3.3V |
| 5 (blk) | - | +3.3V |
| 6 (blk) | GND | GND |
::: info
The TX and RX on the flight controller must be connected to the RX and TX on the FLARM, respectively.
:::
## Software Configuration
### Port Configuration
The recievers are configured in the same way as any other [MAVLink Peripheral](../peripherals/mavlink_peripherals.md).
The only _specific_ setup is that the port baud rate must be set to 57600 and the a low-bandwidth profile (`MAV_X_MODE`).
Assuming you have connected the device to the TELEM2 port, [set the parameters](../advanced_config/parameters.md) as shown:
- [MAV_1_CONFIG](../advanced_config/parameter_reference.md#MAV_1_CONFIG) = TELEM 2
- [MAV_1_MODE](../advanced_config/parameter_reference.md#MAV_1_MODE) = Normal
- [MAV_1_RATE](../advanced_config/parameter_reference.md#MAV_1_RATE) = 0 (default sending rate for port).
- [MAV_1_FORWARD](../advanced_config/parameter_reference.md#MAV_1_FORWARD) = Enabled
Then reboot the vehicle.
You will now find a new parameter called [SER_TEL2_BAUD](../advanced_config/parameter_reference.md#SER_TEL2_BAUD), which must be set to 57600.
### Configure Traffic Avoidance
Configure the action when there is a potential collision using the parameter below:
| Parameter | Description |
| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="NAV_TRAFF_AVOID"></a>[NAV_TRAFF_AVOID](../advanced_config/parameter_reference.md#NAV_TRAFF_AVOID) | Enable traffic avoidance mode specify avoidance response. 0: Disable, 1: Warn only, 2: Return mode, 3: Land mode. |
| <a id="NAV_TRAFF_A_HOR"></a>[NAV_TRAFF_A_HOR](../advanced_config/parameter_reference.md#NAV_TRAFF_A_HOR) | Horizonal radius of cylinder around the vehicle that defines its airspace (i.e. the airspace in the ground plane). |
| <a id="NAV_TRAFF_A_VER"></a>[NAV_TRAFF_A_VER](../advanced_config/parameter_reference.md#NAV_TRAFF_A_VER) | Vertical height above and below vehicle of the cylinder that defines its airspace (also see [NAV_TRAFF_A_HOR](#NAV_TRAFF_A_HOR)). |
| <a id="NAV_TRAFF_COLL_T"></a>[NAV_TRAFF_COLL_T](../advanced_config/parameter_reference.md#NAV_TRAFF_COLL_T) | Collision time threshold. Avoidance will trigger if the estimated time until collision drops below this value (the estimated time is based on relative speed of traffic and UAV). |
## Implementation
### ADSB/FLARM
PX4 listens for valid transponder reports during missions.
If a valid transponder report is received, PX4 first uses the traffic transponder information to estimate whether the traffic heading and height indicates there will be an intersection with the airspace of the UAV.
The UAV airspace consists of a surrounding cylinder defined by the radius [NAV_TRAFF_A_HOR](#NAV_TRAFF_A_HOR) and height [NAV_TRAFF_A_VER](#NAV_TRAFF_A_VER), with the UAV at it's center.
The traffic detector then checks if the time until intersection with the UAV airspace is below the [NAV_TRAFF_COLL_T](#NAV_TRAFF_COLL_T) threshold based on the relative speed.
If the both checks are true, the [Traffic Avoidance Failsafe](../config/safety.md#traffic-avoidance-failsafe) action is started, and the vehicle will either warn, land, or return.
The code can be found in `Navigator::check_traffic` ([/src/modules/navigator/navigator_main.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/navigator/navigator_main.cpp)).
PX4 will also forward the transponder data to a GCS if this has been configured for the MAVLink instance (this is recommended).
The last 10 Digits of the GUID is displayed as Drone identification.
### UTM
PX4 listens for `UTM_GLOBAL_POSITION` MAVLink messages during missions.
When a valid message is received, its validity flags, position and heading are mapped into the same `transponder_report` UORB topic used for _ADS-B traffic avoidance_.
The implementation is otherwise _exactly_ as described in the section above.
::: info
[UTM_GLOBAL_POSITION](https://mavlink.io/en/messages/common.html#UTM_GLOBAL_POSITION) contains additional fields that are not provided by an ADSB transponder (see [ADSB_VEHICLE](https://mavlink.io/en/messages/common.html#ADSB_VEHICLE)).
The current implementation simply drops the additional fields (including information about the vehicle's planned next waypoint).
:::
## Testing/Simulated ADSB Traffic
You can simulate ADS-B traffic for testing.
Note that this requires that you [Build PX4](../dev_setup/building_px4.md).
::: info
Simulated ADS-B traffic can trigger real failsafe actions.
Use with care in real flight!
:::
To enable this feature:
1. Uncomment the code in `AdsbConflict::run_fake_traffic()`([AdsbConflict.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/lib/adsb/AdsbConflict.cpp#L342C1-L342C1)).
1. Rebuild and run PX4.
1. Execute the [`navigator fake_traffic` command](../modules/modules_controller.md#navigator) in the [QGroundControl MAVLink Shell](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/analyze_view/mavlink_console.html) (or some other [PX4 Console or MAVLink shell](../debug/consoles.md), such as the PX4 simulator terminal).
The code in `run_fake_traffic()` is then executed.
You should see ADS-B warnings in the Console/MAVLink shell, and QGC should also show an ADS-B traffic popup.
By default `run_fake_traffic()` publishes a number of traffic messages (it calls [`AdsbConflict::fake_traffic()`](#fake-traffic-method) to emit each report).
These simulate ADS-B traffic where there may be a conflict, where there won't be a conflict, as well as spamming the traffic buffer.
::: details Information about the test methods
The relevent methods are defined in [AdsbConflict.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/lib/adsb/AdsbConflict.cpp#L342C1-L342C1).
#### `run_fake_traffic()` method
The `run_fake_traffic()` method is run when the `navigator fake_traffic` command is called.
The method calls the `fake_traffic()` method to generate simulated transponder messages around the current vehicle position.
It passes in the current vehicle position, and information about the simulated traffic, such as callsign, distances, directions, altitude differences, velocities, and emitter types.
The (commented out) code in `run_fake_traffic()` simulates a number of different scenarios, including conflicts and non-conflicts, as well as spamming the traffic buffer.
#### `fake_traffic()` method
`AdsbConflict::fake_traffic()` is called by the [`run_fake_traffic()`](#run-fake-traffic-method) to create individual ADS-B transponder reports.
This takes several parameters, which specify the characteristics of the fake traffic:
- `callsign`: Callsign of the fake transponder.
- `distance`: Horizontal distance to the fake vehicle from the current vehicle.
- `direction`: Direction in NED from this vehicle to the fake in radians.
- `traffic_heading`: Travel direction of the traffic in NED in radians.
- `altitude_diff`: Altitude difference of the fake traffic. Positive is up.
- `hor_velocity`: Horizontal velocity of fake traffic, in m/s.
- `ver_velocity`: Vertical velocity of fake traffic, in m/s.
- `emitter_type`: Type of fake vehicle, as an enumerated value.
- `icao_address`: ICAO address.
- `lat_uav`: Lat of this vehicle (used to position fake traffic around vehicle)
- `on_uav`: Lon of this vehicle (used to position fake traffic around vehicle)
- `alt_uav`: Altitude of the vehicle (as reference - used to position fake traffic around vehicle)
The method creates a simulated transponder message near the vehicle, using following steps:
- Calculates the latitude and longitude of the traffic based on the UAV's position, distance, and direction.
- Computes the new altitude by adding the altitude difference to the UAV's altitude.
- Populates a [TransponderReport](../msg_docs/TransponderReport.md) topic with the simulated traffic data.
- If the board supports a Universally Unique Identifier (UUID), the method retrieves the UUID using `board_get_px4_guid` and copies it to the `uas_id` field of the structure.
Otherwise, it generates a simulated GUID.
- Publishes the simulated traffic message using `orb_publish`.
:::
<!-- See also implementation PR: https://github.com/PX4/PX4-Autopilot/pull/21283 -->
<!-- See also bug to make this work without uncommenting: https://github.com/PX4/PX4-Autopilot/issues/21810 -->
## Further Information
- [MAVLink Peripherals](../peripherals/mavlink_peripherals.md)
- [Serial Port Configuration](../peripherals/serial_configuration.md)
docs/en/peripherals/camera.md
+1
View File
@@ -0,0 +1 @@
<Redirect to="../camera/configuration" />
docs/en/peripherals/camera_t265_vio.md
+1
View File
@@ -0,0 +1 @@
<Redirect to="../camera/camera_intel_realsense_t265_vio" />
docs/en/peripherals/dshot.md
+149
View File
@@ -0,0 +1,149 @@
# DShot ESCs
DShot is an alternative ESC protocol that has several advantages over [PWM](../peripherals/pwm_escs_and_servo.md) or [OneShot](../peripherals/oneshot.md):
- Reduced latency.
- Increased robustness via a checksum.
- No need for ESC calibration as the protocol uses digital encoding.
- Telemetry feedback is available/supported on some ESCs.
- Can reverse motor spin directions via commands when needed (rather than physically moving wires/re-soldering).
- Other useful commands are supported.
This topic shows how to connect and configure DShot ESCs.
## Wiring/Connections {#wiring}
DShot ESC are wired the same way as [PWM ESCs](pwm_escs_and_servo.md).
The only difference is that they can only be connected to the FMU, and usually only to some subset of pins.
::: info
You may want to check the actuator configuration screen to see what pins are available for DShot on your controller before wiring up!
:::
Pixhawk controllers with both an FMU and an IO board usually label them as `AUX` (FMU) and `MAIN` (IO), respectively.
These match the `PWM AUX` and `PWM MAIN` output tabs on the actuator configuration screen.
For these controllers connect the DShot ESC to the `AUX` port.
Controllers that don't have an IO board usually label the (single) output port as `MAIN`, and this is where you will connect your DShot ESC.
If the controller without IO has its own firmware, the actuator assignment will be to the matching `PWM MAIN` outputs.
However if the same firmware is used for hardware with/without the IO board, such as for the Pixhawk 4 and Pixhawk 4 Mini, then actuator assignment tab used is the same in both cases: `PWM AUX` (i.e. not matching the port label `MAIN` in the "mini" case).
## Configuration
:::warning
Remove propellers before changing ESC configuration parameters!
:::
Enable DShot for your required outputs in the [Actuator Configuration](../config/actuators.md).
DShot comes with different speed options: _DShot150_, _DShot300_, _DShot600_ and _DShot1200_, where the number indicates the speed in kilo-bits/second.
You should set the parameter to the highest speed supported by your ESC (according to its datasheet).
Then connect the battery and arm the vehicle.
The ESCs should initialize and the motors turn in the correct directions.
- If the motors do not spin in the correct direction (for the [selected airframe](../airframes/airframe_reference.md)) you can reverse them in the UI using the **Set Spin Direction** option (this option appears after you select DShot and assign motors).
You can also reverse motors by sending an [ESC Command](#commands).
## ESC Commands {#commands}
Commands can be sent to the ESC via the [MAVLink shell](../debug/mavlink_shell.md).
See [here](../modules/modules_driver.md#dshot) for a full reference of the supported commands.
The most important ones are:
- Make a motor connected to to FMU output pin 1 beep (helps with identifying motors)
```sh
dshot beep1 -m 1
```
- Retrieve ESC information (requires telemetry, see below):
```sh
nsh> dshot esc_info -m 2
INFO [dshot] ESC Type: #TEKKO32_4in1#
INFO [dshot] MCU Serial Number: xxxxxx-xxxxxx-xxxxxx-xxxxxx
INFO [dshot] Firmware version: 32.60
INFO [dshot] Rotation Direction: normal
INFO [dshot] 3D Mode: off
INFO [dshot] Low voltage Limit: off
INFO [dshot] Current Limit: off
INFO [dshot] LED 0: unsupported
INFO [dshot] LED 1: unsupported
INFO [dshot] LED 2: unsupported
INFO [dshot] LED 3: unsupported
```
- Permanently set the spin direction of a motor connected to FMU output pin 1 (while motors are _not_ spinning):
- Set spin direction to `reversed`:
```sh
dshot reverse -m 1
dshot save -m 1
```
Retrieving ESC information will then show:
```sh
Rotation Direction: reversed
```
- Set spin direction to `normal`:
```sh
dshot normal -m 1
dshot save -m 1
```
Retrieving ESC information will then show:
```sh
Rotation Direction: normal
```
::: info
- The commands will have no effect if the motors are spinning, or if the ESC is already set to the corresponding direction.
- The ESC will revert to its last saved direction (normal or reversed) on reboot if `save` is not called after changing the direction.
:::
## Telemetry
Some ESCs are capable of sending telemetry back to the flight controller, including:
- temperature
- voltage
- current
- accumulated current consumption
- RPM values
These DShot ESCs will have an additional telemetry wire.
To enable this feature (on ESCs that support it):
1. Join all the telemetry wires from all the ESCs together, and then connect them to one of the RX pins on an unused flight controller serial port.
1. Enable telemetry on that serial port using [DSHOT_TEL_CFG](../advanced_config/parameter_reference.md#DSHOT_TEL_CFG).
After a reboot you can check if telemetry is working (make sure the battery is connected) using:
```sh
dshot esc_info -m 1
```
:::tip
You may have to configure [MOT_POLE_COUNT](../advanced_config/parameter_reference.md#MOT_POLE_COUNT) to get the correct RPM values.
:::
:::tip
Not all DSHOT-capable ESCs support `[esc_info]`(e.g. APD 80F3x), even when telemetry is supported and enabled.
The resulting error is:
```sh
ERROR [dshot] No data received. If telemetry is setup correctly, try again.
```
Check manufacturer documentation for confirmation/details.
:::
docs/en/peripherals/esc_motors.md
+82
View File
@@ -0,0 +1,82 @@
# ESCs & Motors
Many PX4 drones use brushless motors that are driven by the flight controller via an Electronic Speed Controller (ESC).
The ESC takes a signal from the flight controller and uses it to set control the level of power delivered to the motor.
PX4 supports a number of common protocols for sending the signals to ESCs: [PWM ESCs](../peripherals/pwm_escs_and_servo.md), [OneShot ESCs](../peripherals/oneshot.md), [DShot ESCs](../peripherals/dshot.md), [DroneCAN ESCs](../dronecan/escs.md), PCA9685 ESC (via I2C), and some UART ESCs (from Yuneec).
For more information see:
- [PWM ESCs and Servos](../peripherals/pwm_escs_and_servo.md)
- [OneShot ESCs and Servos](../peripherals/oneshot.md)
- [DShot](../peripherals/dshot.md)
- [DroneCAN ESCs](../dronecan/escs.md)
- [ESC Calibration](../advanced_config/esc_calibration.md)
- [ESC Firmware and Protocols Overview](https://oscarliang.com/esc-firmware-protocols/) (oscarliang.com)
A high level overview of the main ESC/Servo protocols supported by PX4 is given below.
## ESC Protocols
### PWM
[PWM ESCs](../peripherals/pwm_escs_and_servo.md) are commonly used for fixed-wing vehicles and ground vehicles (vehicles that require a lower latency like multicopters typically use oneshot or dshot ESCs).
PWM ESCs communicate using a periodic pulse, where the _width_ of the pulse indicates the desired power level.
The pulse wdith typically ranges between 1000uS for zero power and 2000uS for full power.
The periodic frame rate of the signal depends on the capability of the ESC, and commonly ranges between 50Hz and 490 Hz (the theoretical maximum being 500Hz for a very small "off" cycle).
A higher rate is better for ESCs, in particular where a rapid response to setpoint changes is needed.
For PWM servos 50Hz is usually sufficient, and many don't support higher rates.
![duty cycle for PWM](../../assets/peripherals/esc_pwm_duty_cycle.png)
In addition to being a relatively slow protocol PWM ESCs require [calibration](../advanced_config/esc_calibration.md) because the range values representing low and high values can vary significantly.
Unlike [dshot](#dshot) and [DroneCAN ESC](#dronecan) they do not have the ability to provide telemetry and feedback on ESC (or servo) state.
Setup:
- [ESC Wiring](../peripherals/pwm_escs_and_servo.md)
- [PX4 Configuration](../peripherals/pwm_escs_and_servo.md#px4-configuration)
- [ESC Calibration](../advanced_config/esc_calibration.md)
### Oneshot 125
[OneShot 125 ESCs](../peripherals/oneshot.md) are usually much faster than PWM ESCs, and hence more responsive and easier to tune.
They are preferred over PWM for multicopters (but not as much as [DShot ESCs](#dshot), which do not require calibration, and may provide telemetry feedback).
There are a number of variants of the OneShot protocol, which support different rates.
PX4 only supports OneShot 125.
OneShot 125 is the same as PWM but uses pulse widths that are 8 times shorter (from 125us to 250us for zero to full power).
This allows OneShot 125 ESCs to have a much shorter duty cycle/higher rate.
For PWM the theoretical maximum is close to 500 Hz while for OneShot it approaches 4 kHz.
The actual supported rate depends on the ESC used.
Setup:
- [ESC Wiring](../peripherals/pwm_escs_and_servo.md) (same as for PWM ESCs)
- [PX4 Configuration](../peripherals/oneshot.md#px4-configuration)
- [ESC Calibration](../advanced_config/esc_calibration.md)
### DShot
[DShot](../peripherals/dshot.md) is a digital ESC protocol that is highly recommended for vehicles that can benefit from reduce latency, in particular racing multicopters, VTOL vehicles, and so on.
It has reduced latency and is more robust than both [PWM](#pwm) and [OneShot](#oneshot-125).
In addition it does not require ESC calibration, telemetry is available from some ESCs, and you can revers motor spin directions
PX4 configuration is done in the [Actuator Configuration](../config/actuators.md).
Selecting a higher rate DShot ESC in the UI result in lower latency, but lower rates are more robust (and hence more suitable for large aircraft with longer leads); some ESCs only support lower rates (see datasheets for information).
Setup:
- [ESC Wiring](../peripherals/pwm_escs_and_servo.md) (same as for PWM ESCs)
- [DShot](../peripherals/dshot.md) also contains information about how to send commands etc.
### DroneCAN
[DroneCAN ESCs](../dronecan/escs.md) are recommended when DroneCAN is the primary bus used for your vehicle.
The PX4 implementation is currently limited to update rates of 200Hz.
DroneCAN shares many similar benefits to [Dshot](#dshot) including high data rates, robust connection over long leads, telemetry feedback, no need for calibration of the ESC itself.
[DroneCAN ESCs](../dronecan/escs.md) are connected via the DroneCAN bus (setup and configuration are covered at that link).
docs/en/peripherals/frsky_telemetry.md
+268
View File
@@ -0,0 +1,268 @@
# FrSky Telemetry
FrSky telemetry allows you to access vehicle [telemetry/status](#messages) information on a compatible RC transmitter.
Available [telemetry is listed here](#messages), and includes: flight mode, battery level, RC signal strength, speed, altitude etc.
Some transmitters can additionally provide audible and vibration feedback, which is particularly useful for low battery and other failsafe warnings.
PX4 supports both [S.Port](#s_port) (new) and D (old) FrSky telemetry ports.
## Hardware Setup
FrSky telemetry requires:
- An [FrSky-compatible RC transmitter](#transmitters) like the FrSky Taranis X9D Plus.
- An [FrSky telemetry-capable receiver](#receivers) like the XSR and X8R.
- A cable to connect the FrSky receiver Smart Port (SPort) to a flight controller UART.
First [connect the receiver for RC channels](../getting_started/rc_transmitter_receiver.md#connecting-receivers), e.g. connect the S.Bus ports on the receiver and the flight controller.
Then set up FrSky telemetry by separately connecting the SPort on the receiver to any free UART on the flight controller, and then [configure PX4 to run FrSky telemetry on that UART](#configure).
This is done slightly differently, depending on whether the SPort receiver has a pin for an uninverted output, and/or the Pixhawk version.
### Pixhawk FMUv4 (and prior)
For Pixhawk FMUv4 and earlier, UART ports and receiver telemetry ports are typically incompatible (with the exception of [Pixracer](../flight_controller/pixracer.md)).
Generally SPort receivers have an _inverted_ S.Port signal and you have to use a converter cable to split the S.Port into uninverted TX and RX for connecting to the Pixhawk UART.
An example is shown below.
![FrSky-Taranis-Telemetry](../../assets/hardware/telemetry/frsky_telemetry_overview.jpg)
:::tip
When connecting to an inverted S.Port it is usually cheaper and easier to buy a [ready made cable](#ready_made_cable) that contains this adapter and has the appropriate connectors for the autopilot and receiver.
Creating a [DIY cable](#diy_cables) requires electronics assembly expertise.
:::
If using an S.Port receiver with a pin for _uninverted output_ you can simply attach one of the UART's TX pins.
<!-- FYI only: The uninverted output can be used in single-wire mode so you don't need both RX and TX wires.
Discussion of that here: https://github.com/PX4/PX4-user_guide/pull/755#pullrequestreview-464046128 -->
Then [configure PX4](#configure).
### Pixhawk FMUv5/STM32F7 and later
For Pixhawk FMUv5 and later PX4 can read either inverted (or uninverted) S.Port signals directly - no special cable is required.
::: info
More generally this is true on autopilots with STM32F7 or later (e.g. [Durandal](../flight_controller/durandal.md) has a STM32H7 and can read inverted or uninverted S.Port signals directly).
:::
Simply attach one of the UART's TX pins to the SPort inverted or uninverted pin (PX4 will auto-detect and handle either type).
Then [configure PX4](#configure).
<a id="configure"></a>
## PX4 Configuration
[Configure the serial port](../peripherals/serial_configuration.md) on which FrSky will run using [TEL_FRSKY_CONFIG](../advanced_config/parameter_reference.md#TEL_FRSKY_CONFIG).
There is no need to set the baud rate for the port, as this is configured by the driver.
::: info
You can use any free UART, but typically `TELEM 2` is used for FrSky telemetry (except for [Pixracer](../flight_controller/pixracer.md), which is pre-configured to use the _FrSky_ port by default).
:::
:::tip
If the configuration parameter is not available in _QGroundControl_ then you may need to [add the driver to the firmware](../peripherals/serial_configuration.md#parameter_not_in_firmware):
```
drivers/telemetry/frsky_telemetry
```
:::
No further configuration is required; FrSky telemetry auto-starts when connected and detects D or S mode.
<a id="transmitters"></a>
## Compatible RC Transmitters
You will need an RC transmitter that can receive the telemetry stream (and that is bound to the FrSky receiver).
Popular alternatives include:
- FrSky Taranis X9D Plus (recommended)
- FrSky Taranis X9D
- FrSky Taranis X9E
- FrSky Taranis Q X7
- Turnigy 9XR Pro
The above transmitters can display telemetry data without any further configuration. The following section(s) explain how you can customise telemetry display (for example, to create a better UI/UX).
### Taranis - LuaPilot Setup
Compatible Taranis receivers (e.g. X9D Plus) running OpenTX 2.1.6 or newer can use the LuaPilot script to modify the displayed telemetry (as shown in the screenshot below).
![Telemetry Screen on the Taranis](../../assets/hardware/telemetry/taranis_telemetry.jpg)
Instructions for installing the script can be found here: [LuaPilot Taranis Telemetry script > Taranis Setup OpenTX 2.1.6 or newer](http://ilihack.github.io/LuaPilot_Taranis_Telemetry/)
If you open the `LuaPil.lua` script with a text editor, you can edit the configuration. Suggested modifications include:
- `local BattLevelmAh = -1` - Use the battery level calculation from the vehicle
- `local SayFlightMode = 0` - There are no WAV files for the PX4 flight modes
<a id="messages"></a>
## Telemetry Messages
FrySky Telemetry can transmit most of the more useful status information from PX4.
S-Port and D-Port receivers transmit different sets of messages, as listed in the following sections.
<a id="s_port"></a>
### S-Port
S-Port receivers transmit the following messages from PX4 (from [here](https://github.com/iNavFlight/inav/blob/master/docs/Telemetry.md#available-smartport-sport-sensors)):
- **AccX, AccY, AccZ:** Accelerometer values.
- **Alt:** Barometer based altitude, relative to home location.
- **Curr:** Actual current consumption (Amps).
- **Fuel:** Remaining battery percentage if `battery_capacity` variable set and variable `smartport_fuel_percent = ON`, mAh drawn otherwise.
- **GAlt:** GPS altitude, sea level is zero.
- **GPS:** GPS coordinates.
- **GSpd:** Current horizontal ground speed, calculated by GPS.
- **Hdg:** Heading (degrees - North is 0°).
- **VFAS:** Actual battery voltage value (Voltage FrSky Ampere Sensor).
- **VSpd:** Vertical speed (cm/s).
- **Tmp1:** [Flight mode](../flight_modes/index.md#flight-modes), sent as an integer: 18 - Manual, 23 - Altitude, 22 - Position, 27 - Mission, 26 - Hold, 28 - Return, 19 - Acro, 24 0 Offboard, 20 - Stabilized, 25 - Takeoff, 29 - Land, 30 - Follow Me.
- **Tmp2:** GPS information. Right-most digit is GPS fix type (0 = none, 2 = 2D, 3 = 3D). Other digits are number of satellites.
::: info
The following "standard" S-Port messages are not supported by PX4: **ASpd**, **A4**.
:::
<!-- FYI:
Values of FRSKY_ID_TEMP1 and FRSKY_ID_TEMP1 set:
- https://github.com/PX4/PX4-Autopilot/blob/main/src/drivers/telemetry/frsky_telemetry/frsky_telemetry.cpp#L85 (get_telemetry_flight_mode)
- https://github.com/PX4/PX4-Autopilot/blob/main/src/drivers/telemetry/frsky_telemetry/frsky_data.cpp#L234-L237
Lua map of flight modes:
- https://github.com/ilihack/LuaPilot_Taranis_Telemetry/blob/master/SCRIPTS/TELEMETRY/LuaPil.lua#L790
-->
### D-port
D-Port receivers transmit the following messages (from [here](https://github.com/cleanflight/cleanflight/blob/master/docs/Telemetry.md)):
- **AccX, AccY, AccZ:** Accelerometer values.
- **Alt:** Barometer based altitude, init level is zero.
- **Cels:** Average cell voltage value (battery voltage divided by cell number).
- **Curr:** Actual current consumption (Amps).
- **Fuel:** Remaining battery percentage if capacity is set, mAh drawn otherwise.
- **Date:** Time since powered.
- **GAlt:** GPS altitude, sea level is zero.
- **GPS:** GPS coordinates.
- **GSpd:** Current speed, calculated by GPS.
- **Hdg:** Heading (degrees - North is 0°).
- **RPM:** Throttle value if armed, otherwise battery capacity. Note that blade number needs to be set to 12 in Taranis.
- **Tmp1:** Flight mode (as for S-Port).
- **Tmp2:** GPS information (as for S-Port).
- **VFAS:** Actual battery voltage value (Voltage FrSky Ampere Sensor).
- **Vspd:** Vertical speed (cm/s).
<a id="receivers"></a>
## FrSky Telemetry Receivers
Pixhawk/PX4 supports D (old) and S (new) FrSky telemetry. The table belows all FrSky receivers that support telemetry via a D/S.PORT (in theory all of these should work).
:::tip
Note that the X series receivers listed below are recommended (e.g. XSR, X8R). The R and G series have not been tested/validated by the test team, but should work.
:::
| Receiver | Range | Combined output | Digital telemetry input | Dimensions | Weight |
| ----------- | ----- | --------------------- | ----------------------------- | --------------------- | ------ |
| D4R-II | 1.5km | CPPM (8) | D.Port | 40x22.5x6mm | 5.8g |
| D8R-XP | 1.5km | CPPM (8) | D.Port | 55x25x14mm | 12.4g |
| D8R-II Plus | 1.5km | no | D.Port | 55x25x14mm | 12.4g |
| X4R | 1.5km | CPPM (8) | Smart Port | 40x22.5x6mm | 5.8g |
| X4R-SB | 1.5km | S.Bus (16) | Smart Port | 40x22.5x6mm | 5.8g |
| X6R / S6R | 1.5km | S.Bus (16) | Smart Port | 47.42×23.84×14.7mm | 15.4g |
| X8R / S8R | 1.5km | S.Bus (16) | Smart Port | 46.25 x 26.6 x 14.2mm | 16.6g |
| XSR / XSR-M | 1.5km | S.Bus (16) / CPPM (8) | Smart Port | 26x19.2x5mm | 3.8g |
| RX8R | 1.5km | S.Bus (16) | Smart Port | 46.25x26.6x14.2mm | 12.1g |
| RX8R PRO | 1.5km | S.Bus (16) | Smart Port | 46.25x26.6x14.2mm | 12.1g |
| R-XSR | 1.5km | S.Bus (16) / CPPM (8) | Smart Port | 16x11x5.4mm | 1.5g |
| G-RX8 | 1.5km | S.Bus (16) | Smart Port + integrated vario | 55.26*17*8mm | 5.8g |
| R9 | 10km | S.Bus (16) | Smart Port | 43.3x26.8x13.9mm | 15.8g |
| R9 slim | 10km | S.Bus (16) | Smart Port | 43.3x26.8x13.9mm | 15.8g |
::: info
The above table originates from http://www.redsilico.com/frsky-receiver-chart and FrSky [product documentation](https://www.frsky-rc.com/product-category/receivers/).
:::
<a id="ready_made_cable"></a>
## Ready-Made Cables
Ready-made cables for use with Pixhawk FMUv4 and earlier (except for Pixracer) are available from:
- [Craft and Theory](http://www.craftandtheoryllc.com/telemetry-cable). Versions are available with DF-13 compatible _PicoBlade connectors_ (for FMUv2/3DR Pixhawk, FMUv2/HKPilot32) and _JST-GH connectors_ (for FMUv3/Pixhawk 2 "The Cube" and FMUv4/PixRacer v1).
<a href="http://www.craftandtheoryllc.com/telemetry-cable"><img src="../../assets/hardware/telemetry/craft_and_theory_frsky_telemetry_cables.jpg" alt="Purchase cable here from Craft and Theory"></a>
<a id="diy_cables"></a>
## DIY Cables
It is possible to create your own adapter cables.
You will need connectors that are appropriate for your autopilot (e.g. _JST-GH connectors_ for FMUv3/Pixhawk 2 "The Cube" and FMUv4/PixRacer v1, and DF-13 compatible _PicoBlade connectors_ for older autopilots).
The Pixracer includes electronics for converting between S.PORT and UART signals, but for other boards you will need a UART to S.PORT adapter.
These can be sourced from:
- [FrSky FUL-1](https://www.frsky-rc.com/product/ful-1/): [unmannedtech.co.uk](https://www.unmannedtechshop.co.uk/frsky-transmitter-receiver-upgrade-adapter-ful-1/)
- SPC: [getfpv.com](http://www.getfpv.com/frsky-smart-port-converter-cable.html), [unmannedtechshop.co.uk](https://www.unmannedtechshop.co.uk/frsky-smart-port-converter-spc/)
More information about the connections for different boards is given below.
### Pixracer to S-port Receivers
Connect the Pixracer FrSky TX and RX lines together (solder the wires together) to the X series receiver's S.port pin.
GND need not be attached as this will have been done when attaching to S.Bus (normal RC connection).
The S-port connection is shown below (using the provided I/O Connector).
![Grau b Pixracer FrSkyS.Port Connection](../../assets/flight_controller/pixracer/grau_b_pixracer_frskys.port_connection.jpg)
![Pixracer FrSkyS.Port Connection](../../assets/flight_controller/pixracer/pixracer_FrSkyTelemetry.jpg)
### Pixracer to D-port Receivers
:::tip
The vast majority of users now prefer to use S.PORT.
:::
Connect the Pixracer FrSky TX line (FS out) to the receiver's RX line.
Connect the Pixracer FrSky RX line (FS in) to the receivers TX line.
GND need not be connected as this will have been done when attaching to RC/SBus (for normal RC).
<!-- Image would be nice -->
### Pixhawk Pro
[Pixhawk 3 Pro](../flight_controller/pixhawk3_pro.md) can be connected to TELEM4 (no additional software configuration is needed).
You will need to connect via a UART to S.PORT adapter board, or a [ready-made cable](#ready_made_cable).
### Pixhawk FMUv5 and later
Simply attach one of the UART's TX pins to the SPort inverted or uninverted pin (PX4 will auto-detect and handle either type).
### Other Boards
Most other boards connect to the receiver for FrSky telemetry via the TELEM2 UART.
This includes, for example: [Pixhawk 1](../flight_controller/pixhawk.md), [mRo Pixhawk](../flight_controller/mro_pixhawk.md), Pixhawk2.
You will need to connect via a UART to S.PORT adapter board, or a [ready-made cable](#ready_made_cable).
<!-- ideally add diagram here -->
## Additional Information
For additional information, see the following links:
- [FrSky Taranis Telemetry](https://github.com/Clooney82/MavLink_FrSkySPort/wiki/1.2.-FrSky-Taranis-Telemetry)
- [Taranis X9D: Setting Up Telemetry](https://www.youtube.com/watch?v=x14DyvOU0Vc) (Video Tutorial)
- [Px4 FrSky Telemetry Setup with Pixhawk2 and X8R Receiver](https://discuss.px4.io//t/px4-frsky-telemetry-setup-with-pixhawk2-and-x8r-receiver/6362) (DIY Cables)
docs/en/peripherals/gripper.md
+120
View File
@@ -0,0 +1,120 @@
# Grippers
Grippers are mechanical devices that can be integrated with an unmanned vehicle to grip (hold) and release payloads.
PX4 allows grippers to be triggered automatically in [Payload Delivery Missions](../flying/package_delivery_mission.md) or manually [using a Joystick](#qgc-joystick-configuration).
![High-load gripper example](../../assets/hardware/grippers/highload_gripper_example.jpg)
::: info
A gripper can instead be configured as a [generic RC or MAVLink actuator](../payloads/generic_actuator_control.md#generic-actuator-control-with-rc).
A generic actuator cannot be used with a joystick or in payload missions, but it can be used with an RC Controller.
:::
## Supported Grippers
There are many different gripper mechanisms ("jaws", "fingers", "electromagnets") and interfaces (PWM, CAN, MAVLink, and so on).
PX4 supports grippers that have simple triggers to hold and release, and that use the following interfaces (see linked documents for details):
- [PWM Servo Gripper](gripper_servo.md) - Grippers connected to autopilot PWM outputs
- **MAVLink Gripper** (Untested) - Grippers that support the [MAV_CMD_DO_GRIPPER](https://mavlink.io/en/messages/common.html#MAV_CMD_DO_GRIPPER) MAVLink command.
## Using a Gripper
For information on using a gripper in missions see [Payload Delivery Missions](../flying/package_delivery_mission.md).
You can manually trigger a gripper manually from a Joystick button if you've mapped `gripper open` and `gripper close` buttons in the [QGC Joystick Configuration](#qgc-joystick-configuration).
Note that if you press the **Grab** button while the gripper is opening, it will automatically abort releasing behavior and go to the closed position, effectively cancelling the release command.
If you do this in a mission while the release is actually happening, then the [delivery will be cancelled](../flying/package_delivery_mission.md#manual-control-of-gripper-in-missions).
Manually triggering a gripper from an [RC Control](../getting_started/rc_transmitter_receiver.md) switch is not supported.
MAVLink applications, such as ground stations, can also control the gripper using the [MAV_CMD_DO_GRIPPER](https://mavlink.io/en/messages/common.html#MAV_CMD_DO_GRIPPER) MAVLink command.
## PX4 Configuration
### Package Delivery Configuration
PX4 gripper support is tied to the package delivery feature, which must be enabled and configured in order to be able to use a gripper.
1. Set [PD_GRIPPER_EN](../advanced_config/parameter_reference.md#PD_GRIPPER_EN) parameter to 1 (reboot required after change).
1. Set [PD_GRIPPER_TYPE](../advanced_config/parameter_reference.md#PD_GRIPPER_TYPE) to match your gripper.
For example, set to `Servo` for a [Servo Gripper](gripper_servo.md).
### Gripper Actuator Mapping
Grippers that are connected directly to a flight controller, such as PWM servo grippers, must be mapped to specific outputs during [Actuator Configuration](../config/actuators.md#actuator-outputs).
This is done by assigning the `Gripper` function to the to the output port where the gripper is connected.
For example, the image below assigns `Gripper` to the PWM AUX5 output.
![Gripper output mapping](../../assets/config/gripper/qgc_gripper_actuator_output_small.png)
Additional information about actuator mapping is provided in the gripper-specific documentation.
For example, see [Gripper Servo > Actuator Mapping](../peripherals/gripper_servo.md#actuator-mapping).
### Enable Pre-ARM Mode
Typically you will want to enable the [pre-arming mode](../advanced_config/prearm_arm_disarm.md).
This mode keeps the motors disabled but allows the gripper to be opened and closed for attaching the payload (avoiding potential danger from spinning propellers).
1. Set [COM_PREARM_MODE](../advanced_config/parameter_reference.md#COM_PREARM_MODE) to `Always`.
### Gripper Actuation Timeout
It is important for package delivery that the gripper has time to release before progressing to subsequent waypoints.
For grippers that do not provide sensor-based feedback of their state, which is most of them, a configurable timeout is used to signal when the gripper _should_ have opened or closed.
To set the actuation timeout:
1. Measure the time taken for the gripper to open and time to close, and note the longer of these two times.
There are two easy ways to open and close the gripper.
While the drone is on a bench and the propellers are removed:
- Run the `payload_deliverer` test in the QGC [MAVLink Shell](../debug/mavlink_shell.md):
```sh
> payload_deliverer gripper_test
```
::: info
If you get an error message like "[payload_deliverer] not running", repeat the setup procedures above.
You might also run the `payload_deliverer start` command in the Nuttx shell.
:::
- Use the [Joystick](#qgc-joystick-configuration) to trigger gripper open and close actions.
1. Set [PD_GRIPPER_TO](../advanced_config/parameter_reference.md#PD_GRIPPER_TO) to whichever of the gripper open and close time is larger.
### Mission Command Timeout
When running a [Payload Delivery Mission](../flying/package_delivery_mission.md) it is important that the mission is not halted in the case where the gripper does not report that it has opened (or closed).
This might happen if a gripper does not have a feedback sensor, if the feedback sensor was damaged, or if UORB dropped the gripper actuator timeout message.
::: info
Gripper state feedback from a sensor is not actually supported yet, but it may be in future.
:::
The mission command timeout provides an additional safeguard, continuing the mission if the gripper's successful actuation acknowledgement is not received.
This timeout is also used to provide a sufficient delay for other commands to complete in the case where sensor feedback is not provided or received, such as for winch deployment/retraction, and gimbal movement to a mission-commanded orientation.
To set the timeout:
1. Set [MIS_COMMAND_TOUT](../advanced_config/parameter_reference.md#MIS_COMMAND_TOUT) to a value greater than the [gripper actuation timeout](#gripper-actuation-timeout).
## QGC Joystick Configuration
QGroundControl [Joystick](../config/joystick.md) configuration allows you to map gripper actions to Joystick buttons, after which you will be open and close the gripper manually.
To map joystick buttons in QGroundControl:
1. Open the menu: **QGC Logo (upper-left) > Vehicle Setup > Joystick > Button Assignment** tab.
![Gripper action mapping](../../assets/config/gripper/qgc_gripper_actions_joystick.png)
1. Select `Gripper Open` and `Gripper Close` actions for your desired joystick buttons, as shown above.
You can test the actions by clicking on the mapped buttons and checking for gripper movement.
If the gripper doesn't move as expected check the package delivery configuration and actuator mapping are set up properly.
docs/en/peripherals/gripper_servo.md
+60
View File
@@ -0,0 +1,60 @@
# PWM Servo Gripper
This section explains how to connect and configure a [gripper](../peripherals/gripper.md) that is controlled using a flight controller PWM output (a servo actuator).
![R4-EM-R22-16: High-load gripper example](../../assets/hardware/grippers/highload_gripper_example.jpg)
## Supported Grippers
The following PWM-connected servos have been tested with PX4:
- [R4-EM-R22-161 : push-to-close latch electronic lock](https://southco.com/en_any_int/r4-em-r22-161).
## Connecting a PWM-controlled Gripper
The PWM cable comprises of three lines: power, ground and signal.
A typical connector is shown in the image below:
![PWM Cable](../../assets/hardware/grippers/pwm_cable.png)
In the image above the wire colors have the following meanings:
| Wire color | Purpose |
| ---------- | ---------- |
| Brown | Ground |
| Red | Power |
| Yellow | PWM Signal |
You would need to connect them into a PWM input of the Flight controller appropriately.
### Compatibility Checks
Before connecting the cable, double-check the following requirements:
- **Signal line voltage level**: Check the data-sheet of your gripper mechanism to find the voltage level of the signal line. And make sure this is compatible with the voltage level of the pins of your Flight Controller.
- **Power requirements of gripper**: Check the mechanism's data-sheet to find out the power line voltage level requirements. Depending on that, the gripper can be either connected directly to the [power module](../power_module/index.md) or connected to a 5V line.
Alternatively a custom voltage regulator can be used to output any other voltage required.
## PX4 Configuration
Configuration instructions can be found in: [Gripper > PX4 Configuration](../peripherals/gripper.md#px4-configuration) documentation.
In particular, note that a servo gripper must be mapped to an output as shown below.
### Actuator Mapping
PWM servo grippers, and other peripherals connected directly to PWM outputs, must be mapped to specific outputs during [Actuator Configuration](../config/actuators.md#actuator-outputs).
This is done by assigning the `Gripper` function to the to the output port where the gripper is connected.
For example, the image below assigns `Gripper` to the PWM AUX5 output.
![Gripper output mapping](../../assets/config/gripper/qgc_gripper_output_setup.png)
You must also set the correct PWM frequency for the gripper output port(for commercial servos / grippers this is normally 50Hz).
::: info
Mis-configuring the frequency may damaging the gripper.
:::
The sliders in the [Actuator Testing](../config/actuators.md#actuator-testing) section of the configuration screen can be used to verify that the correct output moves when you move the slider.
The minimum and maximum PWM values should be set such that the servo is fully closed in the disarmed position and fully open at the maximum slider position.
docs/en/peripherals/index.md
+9
View File
@@ -0,0 +1,9 @@
# Peripherals
This section contains topics about peripheral hardware that can be connected to a flight controller (not including [cameras and other payloads](../payloads/index.md)).
The peripherals are not _required_ for flight, but may support it by providing improved safety, or allowing the vehicle to meet regulartory requirements:
- [ADSB/FLARM/UTM (Traffic Avoidance)](../peripherals/adsb_flarm.md)
- [Parachute](../peripherals/parachute.md)
- [Remote ID](../peripherals/remote_id.md)
docs/en/peripherals/mavlink_peripherals.md
+115
View File
@@ -0,0 +1,115 @@
# MAVLink Peripherals (GCS/OSD/Companion)
Ground Control Stations (GCS), On-Screen Displays (OSD), Companion Computers, ADS-B receivers, and other MAVLink peripherals interact with PX4 using separate MAVLink streams, sent via different serial ports.
In order to configure that a particular serial port is used for MAVLink traffic with a particular peripheral, we use [Serial Port Configuration](../peripherals/serial_configuration.md), assigning one of the abstract "MAVLink instance" configuration parameters to the desired port.
We then set other properties of the MAVLink channel using the parameters associated with our selected MAVLink instance, so that they match the requirements of our particular peripheral.
The most relevant parameters are described below (the full set are listed in the [Parameter Reference > MAVLink](../advanced_config/parameter_reference.md#mavlink)).
## MAVLink Instances
In order to assign a particular peripheral to a serial port we use the concept of a _MAVLink instance_.
Each MAVLink instance represents a particular MAVLink configuration that you can apply to a particular port.
At time of writing three MAVLink _instances_ are defined, each represented by a parameter [MAV_X_CONFIG](#MAV_X_CONFIG), where X is 0, 1, 2.
Each instance has associated parameters that you can use to define the properties of the instance on that port, such as the set of streamed messages (see [MAV_X_MODE](#MAV_X_MODE) below), data rate ([MAV_X_RATE](#MAV_X_RATE)), whether incoming traffic is forwarded to other MAVLink instances ([MAV_X_FORWARD](#MAV_X_FORWARD)), and so on.
::: info
MAVLink instances are an abstract concept for a particular MAVLink configuration.
The number in the name means nothing; you can assign any instance to any port.
:::
The parameters for each instance are:
- <a id="MAV_X_CONFIG"></a>[MAV_X_CONFIG](../advanced_config/parameter_reference.md#MAV_0_CONFIG) - Set the serial port (UART) for this instance "X", where X is 0, 1, 2.
It can be any unused port, e.g.: `TELEM2`, `TELEM3`, `GPS2` etc.
For more information see [Serial Port Configuration](../peripherals/serial_configuration.md).
- <a id="MAV_X_MODE"></a>[MAV_X_MODE](../advanced_config/parameter_reference.md#MAV_0_MODE) - Specify the telemetry mode/target (the set of messages to stream for the current instance and their rate).
The default values are:
- _Normal_: Standard set of messages for a GCS.
- _Custom_ or _Magic_: Nothing (in the default PX4 implementation).
Modes may be used for testing when developing a new mode.
- _Onboard_: Standard set of messages for a companion computer.
- _OSD_: Standard set of messages for an OSD system.
- _Config_: Standard set of messages and rate configuration for a fast link (e.g. USB).
- _Minimal_: Minimal set of messages for use with a GCS connected on a high latency link.
- _ExtVision_ or _ExtVisionMin_: Messages for offboard vision systems (ExtVision needed for VIO).
- _Iridium_: Messages for an [Iridium satellite communication system](../advanced_features/satcom_roadblock.md).
::: info
If you need to find the specific set of message for each mode search for `MAVLINK_MODE_` in [/src/modules/mavlink/mavlink_main.cpp](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/mavlink/mavlink_main.cpp).
:::
:::tip
The mode defines the _default_ messages and rates.
A connected MAVLink system can still request the streams/rates that it wants using [MAV_CMD_SET_MESSAGE_INTERVAL](https://mavlink.io/en/messages/common.html#MAV_CMD_SET_MESSAGE_INTERVAL).
:::
- <a id="MAV_X_RATE"></a>[MAV_X_RATE](../advanced_config/parameter_reference.md#MAV_0_MODE) - Set the maximum _data rate_ for this instance (bytes/second).
- This is the combined rate for all streams of individual message (the rates for individual messages are reduced if the total rate exceeds this value).
- The default setting will generally be acceptable, but might be reduced if the telemetry link becomes saturated and too many messages are being dropped.
- A value of 0 sets the data rate to half the theoretical value.
- <a id="MAV_X_FORWARD"></a>[MAV_X_FORWARD](../advanced_config/parameter_reference.md#MAV_0_FORWARD) - Enable forwarding of MAVLink packets received by the current instance onto other interfaces.
This might be used, for example, to transfer messages between a GCS and a companion computer so that the GCS can talk to a MAVLink enabled camera connected to the companion computer.
Next you need to set the baud rate for the serial port you assigned above (in `MAV_X_CONFIG`).
:::tip
You will need to reboot PX4 to make the parameter available (i.e. in QGroundControl).
:::
The parameter used will depend on the [assigned serial port](../advanced_config/parameter_reference.md#serial) - for example: `SER_GPS1_BAUD`, `SER_TEL2_BAUD`, etc.
The value you use will depend on the type of connection and the capabilities of the connected MAVLink peripheral.
<a id="default_ports"></a>
## Default MAVLink Ports
### TELEM1
The `TELEM 1` port is almost always configured by default for the GCS telemetry stream ("Normal").
To support this there is a [default serial port mapping](../peripherals/serial_configuration.md#default_port_mapping) of MAVLink instance 0 as shown below:
- [MAV_0_CONFIG](../advanced_config/parameter_reference.md#MAV_0_CONFIG) = `TELEM 1`
- [MAV_0_MODE](../advanced_config/parameter_reference.md#MAV_0_MODE) = `Normal`
- [MAV_0_RATE](../advanced_config/parameter_reference.md#MAV_0_RATE)= `1200` Bytes/s
- [MAV_0_FORWARD](../advanced_config/parameter_reference.md#MAV_0_FORWARD) = `True`
- [SER_TEL1_BAUD](../advanced_config/parameter_reference.md#SER_TEL1_BAUD) = `57600`
### TELEM2
The `TELEM 2` port usually configured by default for a companion computer telemetry stream ("Onboard").
To support this there is a [default serial port mapping](../peripherals/serial_configuration.md#default_port_mapping) of MAVLink instance 0 as shown below:
- [MAV_1_CONFIG](../advanced_config/parameter_reference.md#MAV_0_CONFIG) = `TELEM 2`
- [MAV_1_MODE](../advanced_config/parameter_reference.md#MAV_0_MODE) = `Onboard`
- [MAV_1_RATE](../advanced_config/parameter_reference.md#MAV_0_RATE)= `0` (Half maximum)
- [MAV_1_FORWARD](../advanced_config/parameter_reference.md#MAV_0_FORWARD) = `Disabled`
- [SER_TEL2_BAUD](../advanced_config/parameter_reference.md#SER_TEL2_BAUD) = `921600`
### ETHERNET
Pixhawk 5x devices (and later) that have an Ethernet port, configure it by default to connect to a GCS:
On this hardware, there is a [default serial port mapping](../peripherals/serial_configuration.md#default_port_mapping) of MAVLink instance 2 as shown below:
- [MAV_2_CONFIG](../advanced_config/parameter_reference.md#MAV_2_CONFIG) = `Ethernet` (1000)
- [MAV_2_BROADCAST](../advanced_config/parameter_reference.md#MAV_2_BROADCAST) = `1`
- [MAV_2_MODE](../advanced_config/parameter_reference.md#MAV_2_MODE) = `0` (normal/GCS)
- [MAV_2_RADIO_CTL](../advanced_config/parameter_reference.md#MAV_2_RADIO_CTL) = `0`
- [MAV_2_RATE](../advanced_config/parameter_reference.md#MAV_2_RATE) = `100000`
- [MAV_2_REMOTE_PRT](../advanced_config/parameter_reference.md#MAV_2_REMOTE_PRT)= `14550` (GCS)
- [MAV_2_UDP_PRT](../advanced_config/parameter_reference.md#MAV_2_UDP_PRT) = `14550` (GCS)
For more information see: [PX4 Ethernet Setup](../advanced_config/ethernet_setup.md)
## See Also
- [Serial Port Configuration](../peripherals/serial_configuration.md)
- [PX4 Ethernet Setup > PX4 MAVLink Serial Port Configuration](../advanced_config/ethernet_setup.md#px4-mavlink-serial-port-configuration)
- [Serial Port Mapping](../hardware/serial_port_mapping.md)
docs/en/peripherals/oneshot.md
+34
View File
@@ -0,0 +1,34 @@
# OneShot Servos and ESCs (Motor Controllers)
PX4 support OneShot 125 ESCs (only).
These are typically faster and more responsive than [PWM ESCs](../peripherals/pwm_escs_and_servo.md) but share the same wiring setup (all you need to do is set some different parameters)
::: info
[DShot](../peripherals/dshot.md) should always be used instead of OneShot where possible, as it is more responsive, more robust, does not required calibration, and may support telemetry.
The only reason not to use DShot would be hardware limitations (insufficient DShot pins available or using an ESC that does not support DShot).
:::
## Overview
OneShot is essentially a version of [PWM](../peripherals/pwm_escs_and_servo.md) that can be, in theory, up to 8 times faster.
Both PWM and OneShot communicate using a periodic pulse, where the width of the pulse indicates the desired power level.
For PWM the pulse length typically ranges between 1000us (zero) and 2000us (full power), while for OneShot 125 the pulse widths are 8 times shorter, ranging from 125us (zero power) to 250us (full power).
The theoretical maximum rate at which pulses can be sent, and hence the responsiveness, depends on the width of the largest pulse.
For PWM this rate is close to 500 Hz while for OneShot it approaches 4 kHz.
In practice the actual maximum rate for OneShot ESCs is typically between 1 kHz and 2 kHz, depending on the ESC used.
## Setup
### Wiring
Wiring is exactly the same as for [PWM ESCs](../peripherals/pwm_escs_and_servo.md) (and dshot).
### PX4 Configuration
To enable OneShot select the protocol for a group of outputs during [Actuator Configuration](../config/actuators.md).
Note that the output range values are set to values in the normal PWM range (nominally `1000` to `2000`).
These are scaled internally to output appropriate pulse-widths for Oneshot.
Then perform [ESC Calibration](../advanced_config/esc_calibration.md).
docs/en/peripherals/parachute.md
+102
View File
@@ -0,0 +1,102 @@
# Parachute
PX4 can be configured to trigger a parachute during [flight termination](../advanced_config/flight_termination.md).
The parachute can be connected to a free PWM output or via MAVLink.
::: info
During flight termination PX4 turns off all controllers and sets all PWM outputs to their failsafe values (including those connected to PWM outputs) and triggers any connected MAVLink parachutes.
You can therefore use this feature to activate multiple complementary safety devices connected to different outputs.
For more information see [Flight Termination Configuration](../advanced_config/flight_termination.md).
:::
## Using Parachutes
Below are a few considerations when using parachutes:
- A parachute does not guarantee that the vehicle will not be destroyed or cause harm!
You must always fly with safety in mind.
- Parachutes require careful usage to be effective.
For example, they must be folded correctly.
- Parachutes have a minimum effective altitude.
- A parachute may trigger while the vehicle is upside down.
This will increase the time required to slow, and may result in the drone collapsing the parachute.
- The parachute will only deploy if the flight controller is powered and PX4 is running properly (unless it is triggered independently of PX4).
It will not deploy if something causes the flight stack to crash.
## Parachute Setup
Flight termination (and hence parachute deployment) may be triggered by safety checks such as RC Loss, geofence violation, and so on, from attitude triggers and other failure detector checks, or by a command from a ground station.
During flight termination PX4 sets PWM outputs to their "failsafe" values (failsafe values turn off motors, but may be used to turn on/trigger the parachute).
If a MAVLink parachute is connected and healthy, a command will be sent to activate it.
Parachute setup therefore involves:
- Configuring [flight termination](../advanced_config/flight_termination.md) as the appropriate action for those safety and failure cases where the parachute should be deployed.
- Configure PX4 to deploy the parachute during flight termination (set PWM output levels appropriately or send the MAVLink parachute deploy command).
- Configure PX4 output levels to disable motors on failsafe.
This is the default so usually nothing is required (for servos it's the center value).
### Enable Flight Termination
To enable flight termination:
- Set [Safety](../config/safety.md) action to _Flight termination_ for checks where you want the parachute to trigger.
- Set [Failure Detector](../config/safety.md#failure-detector) pitch angles, roll angles and time triggers for crash/flip detection, and disable the failure/IMU timeout circuit breaker (i.e. set [CBRK_FLIGHTTERM=0](../advanced_config/parameter_reference.md#CBRK_FLIGHTTERM)).
::: info
You can also configure an [external Automatic Trigger System (ATS)](../config/safety.md#external-automatic-trigger-system-ats) for failure detection.
:::
### Parachute Output Bus Setup
If the parachute is triggered by a PWM or CAN output then it must first be connected to an unused output.
You will probably also need to separately power the parachute servo.
This is might be done by connecting a 5V BEC to the Flight Controller servo rail, and powering the parachute from it.
You then need to ensure that the parachute pin will be set to a value that will trigger the parachute when a failsafe occurs:
- Open [Actuators](../config/actuators.md) in QGroundControl
- Assign the _Parachute_ function to any unused output (below we set the `AUX6` output):
![Actuators - Parachute (QGC)](../../assets/config/actuators/qgc_actuators_parachute.png)
- Set appropriate PWM values for your parachute.
The output is automatically set to the maximum PWM value when a failsafe is triggered.
::: info
For the spring-loaded launcher from [Fruity Chutes](https://fruitychutes.com/buyachute/drone-and-uav-parachute-recovery-c-21/harrier-drone-parachute-launcher-c-21_33/) the minimum PWM value should be between 700 and 1000ms, and the maximum value between 1800 and 2200ms.
:::
### MAVLink Parachute Setup
PX4 will trigger a connected and healthy parachute on failsafe by sending the command [MAV_CMD_DO_PARACHUTE](https://mavlink.io/en/messages/common.html#MAV_CMD_DO_PARACHUTE) with the [PARACHUTE_RELEASE](https://mavlink.io/en/messages/common.html#PARACHUTE_ACTION) action.
MAVLink parachute support is enabled by setting the parameter [COM_PARACHUTE=1](../advanced_config/parameter_reference.md#COM_PARACHUTE).
PX4 will then indicate parachute status using the [MAV_SYS_STATUS_RECOVERY_SYSTEM](https://mavlink.io/en/messages/common.html#MAV_SYS_STATUS_RECOVERY_SYSTEM) bit in the [SYS_STATUS](https://mavlink.io/en/messages/common.html#SYS_STATUS) extended onboard control sensors fields:
- `SYS_STATUS.onboard_control_sensors_present_extended`: MAVLink parachute present (based on heartbeat detection).
- `SYS_STATUS.onboard_control_sensors_enabled_extended`: ?
- `SYS_STATUS.onboard_control_sensors_health_extended`: MAVLink parachute healthy (based on heartbeat detection).
A MAVLink parachute is required to emit a [HEARTBEAT](https://mavlink.io/en/messages/common.html#HEARTBEAT) with `HEARTBEAT.type` of [MAV_TYPE_PARACHUTE](https://mavlink.io/en/messages/common.html#MAV_TYPE_PARACHUTE).
<!-- PX4 v1.13 support added here: https://github.com/PX4/PX4-Autopilot/pull/18589 -->
## Parachute Testing
:::warning
For the first test, try on the bench, without the props and with an unloaded parachute device!
:::
::: info
There is no way to recover from a Termination state!
You will need to reboot/power cycle the vehicle for subsequent tests.
:::
The parachute will trigger during [flight termination](../advanced_config/flight_termination.md).
The easiest way to test a (real) parachute is to enable the [failure detector attitude trigger](../config/safety.md#attitude-trigger) and tip the vehicle over.
You can also simulate a parachute/flight termination: [Gazebo Classic > Simulated Parachute/Flight Termination](../sim_gazebo_classic/index.md#simulated-parachute-flight-termination).
docs/en/peripherals/pwm_escs_and_servo.md
+126
View File
@@ -0,0 +1,126 @@
# PWM Servos and ESCs (Motor Controllers)
This section describes how to connect and power PWM-based brushless motor controllers and servos.
## ESC Connection Overview
Each PWM Electronic Speed Controller (ESC) minimally has the following wires:
- Power VBAT (usually thick and red)
- Power GND (usually thick and black)
And on the servo plug:
- PWM signal (usually white or yellow)
- GND (usually black or brown)
The servo plug _may_ also have a +5V wire (usually red or orange).
The purpose of this wire and how it is connected depends on particular ESC and vehicle type.
:::tip
In some cases (see below)the +5V line is not needed.
Instead of cutting the +5V line you can gently lift of the locking tab of the plastic housing of the servo connector for that pin (e.g. using a cutter blade or small screw driver) and pull the pin out.
Isolate it with electrical isolation tape and tape it to the servo cable.
This allows you to easily undo the wire later if needed
:::
## Power Connections
Always connect Power VBAT and GND to the battery, and the PWM signal and GND from the servo plug to the motor.
:::tip
There is **no setup** that does not require signal ground to be connected!
:::
The connection to the +5V wire (if present) depends on the ESC/Vehicle.
### Fixed-wing / VTOL
On a fixed-wing (or VTOL) ESC, the +5V line usually provides the output of a Battery Elimination Circuit (BEC).:
- This can be connected to the Pixhawk servo rail and used to power servos for flaps, ailerons etc.
::: info
It is unsafe to power servos or ESCs from the autopilot's avionics power supply.
This is why **Pixhawk series** flight controllers do not provide power for the servo rail (the AUX servo rail is unpowered and is limited to 1A).
:::
- As a rule of thumb you should only connect the _output of only one BEC_ to the Pixhawk servo rail.
(while it may be possible to connect multiple +5V outputs to the rail, this depends on the ESC model).
### Multicopter
On a multicopter, the +5V line might not be present or (if present) may not be connected.
- Multicopters often do not need servos, and hence do not need to power the Pixhawk servo rail (motors are usually separately powered from a power distribution board).
- There is no harm (or benefit) in connecting the wire to the servo rail.
- DJI ESCs typically include this wire, but it is not connected.
### Opto-isolated ESC
On an opto-isolated ESC **without** BEC, the +5V line might need to be connected and powered (in order to provide power to the ESC microcontroller).
In this case the wire will normally be connected to the flight controller servo rail, and the servo rail must be powered from an additional BEC.
## PX4 Configuration
PWM motors and servos are configured using the [Actuator Configuration](../config/actuators.md) screen in QGroundControl.
After assigning outputs and basic calibration, you may then wish to peform an [ESC Calibration](../advanced_config/esc_calibration.md).
Additional PX4 PWM configuration parameters can be found here: [PWM Outputs](../advanced_config/parameter_reference.md#pwm-outputs).
## Troubleshooting
Pixhawk is compatible with all _PWM ESCs_ on the market.
If a particular ESC is not operational, it is incorrectly wired up or configured.
### Ground Connection
Check that the ground (black wire) of the ESC servo connector is connected to Pixhawk (there is no valid wiring setup that does not have a ground reference).
:::warning
It is unsafe to fly without ground connected.
This is because for every positive pulse (the ESC signal) there needs to be an adjacent ground return path for a clean signal shape.
The image below shows how noisy the signal becomes if GND is not connected.
![PWM without ground](../../assets/hardware/pwm_esc/pwm_without_gnd.png)
:::
### Power Connection / Opto-isolated ESCs
If using an opto-isolated ESC that does not provide a BEC / power output, please ensure that the ESC does not need its +5V line powered for the opto-isolator.
See the first section of this page explains for other power connection considerations.
### Invalid Minimum Value
Some ESCs need to see a special low value pulse before switching on (to protect users who have the throttle stick in the middle position on power-up).
PX4 sends a pulse when the vehicle is disarmed, which silences the ESCs when they are disarmed and ensures that ESCs initialise correctly.
Appropriate values are determined and set as part of the [actuator configuration/testing](../config/actuators.md#actuator-testing) process (internally these set the per-output parameters [PWM_MAIN_DISn](../advanced_config/parameter_reference.md#PWM_MAIN_DIS1) and [PWM_AUX_DISn](../advanced_config/parameter_reference.md#PWM_AUX_DIS1)).
### Timeout
Some ESCs may time out (preventing motor activation) if they have not received a valid low pulse within a few seconds of power on.
PX4 sends an idle/disarmed pulse right after power on to stop ESCs timing out.
Appropriate values are determined and set as part of the [actuator configuration/testing](../config/actuators.md#actuator-testing) process (internally these set the per-output parameters [PWM_MAIN_DISn](../advanced_config/parameter_reference.md#PWM_MAIN_DIS1) and [PWM_AUX_DISn](../advanced_config/parameter_reference.md#PWM_AUX_DIS1)).
### Valid Pulse Shape, Voltage and Update Rate
::: info
This should not be a problem, but is included for completeness
:::
Pixhawk uses active high pulses, as used by all the major brands (Futaba, Spektrum, FrSky).
PWM interfaces are not formally standardised, however, the normal micro controllers all use TTL or CMOS voltage levels.
TTL is defined as low < 0.8V and high > 2.0V with some manufacturers using > 2.4V for additional noise margin.
CMOS logic is defined with similar voltage levels.
5V levels are **never** required to successfully switch to an _on_ state.
:::tip
Futaba, FrSky and Spektrum receivers output 3.3V or 3.0V voltage levels, as they are well above 2.4V.
Pixhawk has adopted this common industry pattern and outputs 3.3V levels on recent boards.
:::
docs/en/peripherals/remote_id.md
+258
View File
@@ -0,0 +1,258 @@
# Remote ID (Open Drone ID)
<Badge type="tip" text="PX4 v1.14" /><Badge type="warning" text="Experimental" />
:::warning Experimental
Remote ID support is experimental.
:::
Remote ID is a government mandated technology for UAVs in Japan, the United States of America and the European Union, designed to enable safe sharing of airspace between UAVs and other aircraft.
The specification requires that UAVs broadcast data such as: real-time location/altitude, serial number, operator ID/location, status, etc.
PX4 works with Remote ID modules that target the FAA [standard Remote ID rules](https://www.faa.gov/uas/getting_started/remote_id).
These are designed to be integrated into the vehicle, and broadcast Open Drone ID messages (Open Drone ID is an open source implementation of Remote ID) using id, position, and other information that is supplied by an autopilot.
The "standard rules" modules enable less restrictive operation than "broadcast rules" modules, which are standalone modules with an integrated GPS that do not have any communication with the autopilot.
## Supported Hardware
::: warning
Remote ID hardware can only be connected via DroneCAN on `main` branch builds (builds _after_ PX4 v1.15).
:::
PX4 integrates with Remote ID hardware that supports:
- [Open Drone ID](https://mavlink.io/en/services/opendroneid.html) MAVLink protocol<Badge type="tip" text="PX4 v1.14" />
- Remote ID over CAN<Badge type="tip" text="PX4 main (v1.16)" />
It has been tested with the following devices:
- [Cube ID](https://docs.cubepilot.org/user-guides/cube-id/cube-id) (CubePilot)
- [Db201](https://dronescout.co/dronebeacon-mavlink-remote-id-transponder/) (BlueMark) - Tested via serial port. Not tested via CAN port.
- [Db202mav](https://dronescout.co/dronebeacon-mavlink-remote-id-transponder/) (BlueMark) - Less expensive variant without CAN port.
- [Holybro RemoteID Module](https://holybro.com/products/remote-id) (Holybro)
Other devices that support the Open Drone ID protocol and DroneCAN should also work (but have not been tested).
## Hardware Setup
Remote ID devices can be connected to any free/unused serial port on the flight controller, or CAN.
Most commonly they are connected directly to the `TELEM2` port (if it is not being use for some other purpose) as this is already configured for MAVLink "by default".
### Cube ID
[Cube ID](https://docs.cubepilot.org/user-guides/cube-id/cube-id) can be connected using a serial or CAN port.
It comes with 6-pin and 4-pin JST-GH 1.25mm cables that can be connected directly to the `TELEM` serial port and `CAN` ports, respectively, on most recent Pixhawk flight controllers.
#### Cube ID Serial Port
If using a different port, or a flight controller that has different connector, you may need to modify the cable.
The pinout of the serial port is shown below.
The TX and RX on the flight controller must be connected to the RX and TX on the Remote ID, respectively.
![Cube ID serial port](../../assets/hardware/remote_id/cube_id/serial_port_connector.jpg)
| Pin | Signal | Volt |
| ------- | -------- | ---- |
| 1 (red) | VCC_5V | 5V |
| 2 (blk) | TX (OUT) | |
| 3 (blk) | RX (IN) | |
| 4 (blk) | GND | 0 |
#### Cube ID CAN Port
![Cube ID CAN port](../../assets/hardware/remote_id/cube_id/can_connector.png)
| Pin | Signal | Volt |
| ------- | ------ | ---- |
| 1 (red) | VCC_5V | 5V |
| 2 (red) | CAN_H | |
| 3 (blk) | CAN_L | |
| 4 (blk) | GND | 0 |
#### Cube ID Firmware
The Cube ID uses proprietary firmware (not [ArduRemoteID](https://github.com/ArduPilot/ArduRemoteID) like some other remote id beacons).
For firmware update instructions see [Cube ID > Updating](https://docs.cubepilot.org/user-guides/cube-id/cube-id#updating).
### BlueMark Db201/Db202mav
[Db201](https://dronescout.co/dronebeacon-mavlink-remote-id-transponder/) or [Db202mav](https://dronescout.co/dronebeacon-mavlink-remote-id-transponder/) can be connected using their serial port.
::: info
The `Db201` also has a CAN port that should work on PX4 `main` builds.
However this has not yet been tested.
:::
They come with a 6-pin JST-GH 1.25mm cable that can be connected directly to the `TELEM` ports on most recent Pixhawk flight controllers.
If using a different serial port (i.e. with fewer pins), or a flight controller that has different connector, you may need to modify the cable.
Information on the port pinout can be found in the [User Guide](https://download.bluemark.io/db200.pdf).
The beacons come preinstalled with recent [ArduRemoteID](https://github.com/ArduPilot/ArduRemoteID) firmware.
The [User Guide](https://download.bluemark.io/db200.pdf) explains how you can update firmware via the web interface, if needed.
More general setup, including how to mount the beacon, is also covered in the [User Guide](https://download.bluemark.io/db200.pdf).
### Holybro Remote ID Module
The [Holybro Remote ID Module](https://holybro.com/products/remote-id) can be connected using a serial or CAN port.
It comes with a 6-pin JST-GH 1.25mm cable that can be connected directly to the `TELEM` ports on most recent Pixhawk flight controllers such as the Pixhawk 6C/6X or Cube Orange.
The module comes preinstalled with recent [ArduRemoteID](https://github.com/ArduPilot/ArduRemoteID) firmware.
The [User Guide](https://docs.holybro.com/radio/remote-id) explains how you can config and update firmware via the web interface, if needed.
#### Holybro Pinouts
![Holybro Remote ID Pinouts](../../assets/peripherals/remoteid_holybro/holybro_remote_id_pinout.jpg)
## PX4 Configuration
### MAVLink Port Configuration
Remote ID hardware connected to a serial port is configured in the same way as any other [MAVLink Peripheral](../peripherals/mavlink_peripherals.md).
Assuming you have connected the device to the `TELEM2` port, [set the parameters](../advanced_config/parameters.md) as shown:
- [MAV_1_CONFIG](../advanced_config/parameter_reference.md#MAV_1_CONFIG) = `TELEM 2`
- [MAV_1_MODE](../advanced_config/parameter_reference.md#MAV_1_MODE) = Normal
- [MAV_1_RATE](../advanced_config/parameter_reference.md#MAV_1_RATE) = 0 (default sending rate for port).
- [MAV_1_FORWARD](../advanced_config/parameter_reference.md#MAV_1_FORWARD) = Enabled
Then reboot the vehicle.
You will now find a new parameter called [SER_TEL2_BAUD](../advanced_config/parameter_reference.md#SER_TEL2_BAUD).
The required baud rate depends on the remote ID used (for Cube ID it must be set to 57600).
<!-- In theory, a Remote ID (or other MAVLink peripheral) that supports WiFi or wired Ethernet network could also be connected over those links. -->
### DroneCAN Configuration
Remote ID hardware connected to a CAN is configured in the same way as any other [DroneCAN Hardware](../dronecan/index.md#px4-configuration).
Specifically, you will have to [enable DroneCAN](../dronecan/index.md#enabling-dronecan) by setting the value of [`UAVCAN_ENABLE`](../advanced_config/parameter_reference.md#UAVCAN_ENABLE) to a non-zero value.
::: tip
The [CAN Remote ID Not Working](../peripherals/remote_id.md#can-remote-id-not-working) explains how you can test the setup, and adjust Remote ID settings if necessary.
:::
### Enable Remote ID
There is no need to explicitly enable Remote ID (supported Remote ID messages are either streamed by default or must be requested in the current implementation, even if no remote ID is connected).
### Prevent Arming based on Remote ID
To only allow arming when a Remote ID is ready, [set](../advanced_config/parameters.md#conditional-parameters) the parameter [COM_ARM_ODID](#COM_ARM_ODID) to `2` (it is disabled by default).
| Parameter | Description |
| ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="COM_ARM_ODID"></a>[COM_ARM_ODID](../advanced_config/parameter_reference.md#COM_ARM_ODID) | Enable Drone ID system detection and health check. `0`: Disable (default), `1`: Warn if Remote ID not detected but still allow arming, `2`: Only allow arming if Remote ID is present. |
## Module Broadcast Testing
Integrators should test than the remote ID module is broadcasting the correct information, such as UAV location, ID, operator ID and so on.
This is most easily done using a 3rd party application on your mobile device:
- [Drone Scanner](https://github.com/dronetag/drone-scanner) (Google Play or Apple App store)
- [OpenDroneID OSM](https://play.google.com/store/apps/details?id=org.opendroneid.android_osm&hl=en&gl=US) (Google Play)
## Implementation
PX4 v1.14 streams these messages by default (in streaming modes: normal, onboard, usb, onboard low bandwidth):
- [OPEN_DRONE_ID_LOCATION](https://mavlink.io/en/messages/common.html#OPEN_DRONE_ID_LOCATION) (1 Hz) - UAV location, altitude, direction, and speed.
- [OPEN_DRONE_ID_SYSTEM](https://mavlink.io/en/messages/common.html#OPEN_DRONE_ID_SYSTEM) (1 Hz) Operator location/altitude, multiple aircraft information (group/swarm, if applicable), full timestamp and possible category/class information.
- Implementation assumes operator is located at vehicle home position (does not yet support getting operator position from GCS).
This is believed to be compliant for broadcast-only Remote IDs.
The following message can be streamed on request (using [MAV_CMD_SET_MESSAGE_INTERVAL](https://mavlink.io/en/messages/common.html#MAV_CMD_SET_MESSAGE_INTERVAL)):
- [OPEN_DRONE_ID_BASIC_ID](https://mavlink.io/en/messages/common.html#OPEN_DRONE_ID_BASIC_ID) - UAV identity information (essentially a serial number)
- PX4 v1.14 specifies a serial number ([MAV_ODID_ID_TYPE_SERIAL_NUMBER](https://mavlink.io/en/messages/common.html#MAV_ODID_ID_TYPE_SERIAL_NUMBER)) but does not use the required format (ANSI/CTA-2063 format).
PX4 prevents arming based on Remote ID health if parameter [COM_ARM_ODID](../advanced_config/parameter_reference.md#COM_ARM_ODID) is set to `2`.
The UAV will then require `HEARTBEAT` messages from the Remote ID as a precondition for arming the UAV.
You can also set the parameter to `1` to warn but still allow arming when Remote ID `HEARTBEAT` messages are not detected.
The following Open Drone ID MAVLink messages are not supported in PX4 v1.14 (to be added by [PX4#21647](https://github.com/PX4/PX4-Autopilot/pull/21647)):
- [OPEN_DRONE_ID_AUTHENTICATION](https://mavlink.io/en/messages/common.html#OPEN_DRONE_ID_AUTHENTICATION) - Provides authentication data for the UAV.
- [OPEN_DRONE_ID_SELF_ID](https://mavlink.io/en/messages/common.html#OPEN_DRONE_ID_SELF_ID) - Operator identity (plain text).
- [OPEN_DRONE_ID_OPERATOR_ID](https://mavlink.io/en/messages/common.html#OPEN_DRONE_ID_OPERATOR_ID) - Operator identity.
- [OPEN_DRONE_ID_ARM_STATUS](https://mavlink.io/en/messages/common.html#OPEN_DRONE_ID_ARM_STATUS) - Status of Remote ID hardware.
Use as condition for vehicle arming, and for Remote ID health check.
- [OPEN_DRONE_ID_SYSTEM_UPDATE](https://mavlink.io/en/messages/common.html#OPEN_DRONE_ID_SYSTEM_UPDATE) - Subset of `OPEN_DRONE_ID_SYSTEM` that can be sent with information at higher rate.
## Compliance
PX4 may not be compliant with the relevant specifications in version 1.14 (which is why this feature is currently experimental).
A working group has been established to evaluate the gaps.
Some known issues are:
- Vehicles must arm conditional on receiving the Remote ID [OPEN_DRONE_ID_ARM_STATUS](https://mavlink.io/en/messages/common.html#OPEN_DRONE_ID_ARM_STATUS) message, with a status that indicates the Remote ID hardware is ready to broadcast.
- PX4 v1.14 does not process `OPEN_DRONE_ID_ARM_STATUS`, and arming is only conditional on the Remote ID device `HEARTBEAT`.
- Health of the Remote ID depends on both receiving a `HEARTBEAT` and the `OPEN_DRONE_ID_ARM_STATUS`.
When flying, a non-armed status for the Remote ID must be published in [OPEN_DRONE_ID_LOCATION.status](https://mavlink.io/en/messages/common.html#OPEN_DRONE_ID_LOCATION) as a Remote ID malfunction.
- PX4 v1.14 does not yet receive `OPEN_DRONE_ID_ARM_STATUS`.
- `OPEN_DRONE_ID_ARM_STATUS` must be forwarded to the GCS, if present for additional error reporting.
- [OPEN_DRONE_ID_BASIC_ID](https://mavlink.io/en/messages/common.html#OPEN_DRONE_ID_BASIC_ID) specifies a serial number in an invalid format (not ANSI/CTA-2063 format).
- The vehicle ID is expected to be tamper resistant.
[PX4-Autopilot/21647](https://github.com/PX4/PX4-Autopilot/pull/21647) is intended to address the known issues.
## Troubleshooting
### CAN Remote ID Not Working
::: info
This information was tested with the CAN Cube ID from CubePilot.
It _should_ also apply to CAN Remote ID modules from other vendors.
:::
To confirm that the Remote ID is working:
- Check that the `OPEN_DRONE_ID_BASIC_ID` and `OPEN_DRONE_ID_LOCATION` messages appear in the QGroundControl [MAVLink Inspector](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/analyze_view/mavlink_inspector.html) (QGC **Analyze Tools > MAVLink Inspector**).
- If those messages are not present, check that the Remote_ID node appears on the UAVCAN list.
Run the following command in the [QGroundControl MAVLink Console](../debug/mavlink_shell.md#qgroundcontrol-mavlink-console):
```sh
uavcan status
```
The connected CAN nodes should appear in the list.
If you only have one CAN component on your system (the remote ID) the list might look like this:
```plain
Online nodes (Node ID, Health, Mode):
125 OK OPERAT
```
The nodes aren't "named" so if you have more than one CAN node you can compare the number of nodes shown with the number expected on your system to see if they match.
Alternatively you can run the `uavcan status` with the Remote ID connected and disconnected and difference the result (which has the benefit that you will then known the Remote ID module's node ID).
If the Remote ID CAN node is present and the messages are not being received, then the Remote ID itself may need to be configured:
1. Open QGroundControl
2. Navigate to the [Application settings](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/settings_view/general.html): **Application Settings > General > Miscellaneous**.
3. Select `Enable Remote ID`.
The Remote ID tab should appear.
::: info
If this option is not present you may be in a very recent version of QGC.
In that case, open the view at: **Application Settings > Remote ID**.
:::
4. Enter the information for Basic, Operator, and Self ID.
Once configured, check the MAVLink Inspector again and check that the `OPEN_DRONE_ID_BASIC_ID` and `OPEN_DRONE_ID_LOCATION` messages are now present.
## See Also
- [Remote Identification of Drones](https://www.faa.gov/uas/getting_started/remote_id) (FAA)
docs/en/peripherals/serial_configuration.md
+149
View File
@@ -0,0 +1,149 @@
# Serial Port Configuration
PX4 defines [default functions](#default-serial-port-configuration) for many flight controller ports, which is why you can plug a GPS module into the port labelled `GPS 1`, an RC receiver into `RC IN`, or a telemetry module into `TELEM 1`, and generally they will just work.
The functions assigned to ports are fully configurable using appropriate parameters (in most cases).
You can assign any unused port to any function, or reassign a port to use it for something else.
The configuration makes it easy to (for example):
- Run MAVLink on a different port, change the streamed messages, or switch a TELEM port to use ROS 2/XRCE-DDS.
- Change the baud rate on a port or set the UDP port
- Setup dual GPS.
- Enable sensors that run on a serial port, such as some [distance sensors](../sensor/rangefinders.md).
::: info
- Some ports cannot be configured because they are used for a very specific purpose such as the system console.
- The mapping of specific devices to port names on the flight controller is explained in [Serial Port Mapping](../hardware/serial_port_mapping.md).
:::
## Configuration Parameters
The serial port configuration parameters allow you to assign a particular function or support for particular hardware to a particular port.
These parameters follow the naming pattern `*_CONFIG` or `*_CFG`
::: info
_QGroundControl_ only displays the parameters for services/drivers that are present in firmware.
:::
At time of writing the current set is:
- GNSS configuration:
- GPS Module: [GPS_1_CONFIG](../advanced_config/parameter_reference.md#GPS_1_CONFIG), [GPS_2_CONFIG](../advanced_config/parameter_reference.md#GPS_2_CONFIG) (for most GPS/GNSS systems)
- [Septentrio GNSS Modules](../gps_compass/septentrio.md): [SEP_PORT1_CFG](../advanced_config/parameter_reference.md#SEP_PORT1_CFG), [SEP_PORT2_CFG](../advanced_config/parameter_reference.md#SEP_PORT2_CFG)
- [Iridium Satellite radio](../advanced_features/satcom_roadblock.md): [ISBD_CONFIG](../advanced_config/parameter_reference.md#ISBD_CONFIG)
- [MAVLink Ports](../peripherals/mavlink_peripherals.md): [MAV_0_CONFIG](../advanced_config/parameter_reference.md#MAV_0_CONFIG), [MAV_1_CONFIG](../advanced_config/parameter_reference.md#MAV_1_CONFIG), [MAV_2_CONFIG](../advanced_config/parameter_reference.md#MAV_2_CONFIG)
- VOXL ESC: [VOXL_ESC_CONFIG](../advanced_config/parameter_reference.md#VOXL_ESC_CONFIG)
- MSP OSD: [MSP_OSD_CONFIG](../advanced_config/parameter_reference.md#MSP_OSD_CONFIG)
- RC Port: [RC_PORT_CONFIG](../advanced_config/parameter_reference.md#RC_PORT_CONFIG)
- [FrSky Telemetry](../peripherals/frsky_telemetry.md): [TEL_FRSKY_CONFIG](../advanced_config/parameter_reference.md#TEL_FRSKY_CONFIG)
- HoTT Telemetry: [TEL_HOTT_CONFIG](../advanced_config/parameter_reference.md#TEL_HOTT_CONFIG)
- [uXRCE-DDS](../middleware/uxrce_dds.md) port: [UXRCE_DDS_CFG](../advanced_config/parameter_reference.md#UXRCE_DDS_CFG),
- Sensors (optical flow, distance sensors): [SENS_CM8JL65_CFG](../advanced_config/parameter_reference.md#SENS_CM8JL65_CFG), [SENS_LEDDAR1_CFG](../advanced_config/parameter_reference.md#SENS_LEDDAR1_CFG), [SENS_SF0X_CFG](../advanced_config/parameter_reference.md#SENS_SF0X_CFG), [SENS_TFLOW_CFG](../advanced_config/parameter_reference.md#SENS_TFLOW_CFG), [SENS_TFMINI_CFG](../advanced_config/parameter_reference.md#SENS_TFMINI_CFG), [SENS_ULAND_CFG](../advanced_config/parameter_reference.md#SENS_ULAND_CFG), [SENS_VN_CFG](../advanced_config/parameter_reference.md#SENS_VN_CFG),
- CRSF RC Input Driver: [RC_CRSF_PRT_CFG](../advanced_config/parameter_reference.md#RC_CRSF_PRT_CFG)
- Sagetech MXS: [MXS_SER_CFG](../advanced_config/parameter_reference.md#MXS_SER_CFG)
- Ultrawideband position sensor: [UWB_PORT_CFG](../advanced_config/parameter_reference.md#UWB_PORT_CFG)
- DShot driver: [DSHOT_TEL_CFG](../advanced_config/parameter_reference.md#DSHOT_TEL_CFG)
Some functions/features may define additional configuration parameters, which will follow a similar naming pattern to the port configuration prefix.
For example, `MAV_0_CONFIG` enables MAVLink on a particular port, but you may also need to set [MAV_0_FLOW_CTRL](../advanced_config/parameter_reference.md#MAV_0_FLOW_CTRL), [MAV_0_FORWARD](../advanced_config/parameter_reference.md#MAV_0_FLOW_CTRL), [MAV_0_MODE](../advanced_config/parameter_reference.md#MAV_0_MODE) and so on.
## How to Configure a Port
All the serial drivers/ports are configured in the same way:
1. Set the configuration parameter for the service/peripheral to the port it will use.
1. Reboot the vehicle in order to make the additional configuration parameters visible.
1. Set the baud rate parameter for the selected port to the desired value (e.g. [SER_GPS1_BAUD](../advanced_config/parameter_reference.md#SER_GPS1_BAUD))
1. Configure module-specific parameters (i.e. MAVLink streams and data rate configuration).
The [GPS/Compass > Secondary GPS](../gps_compass/index.md#dual_gps) section provides a practical example of how to configure a port in _QGroundControl_ (it shows how to use `GPS_2_CONFIG` to run a secondary GPS on the `TELEM 2` port).
Similarly [PX4 Ethernet Setup > PX4 MAVLink Serial Port Configuration](../advanced_config/ethernet_setup.md#px4-mavlink-serial-port-configuration) explains the setup for Ethernet serial ports, and [MAVLink Peripherals (OSD/GCS/Companion Computers/etc.)](../peripherals/mavlink_peripherals.md) explains the configuration for MAVLink serial ports.
## Deconflicting Ports
Port conflicts are handled by system startup, which ensures that at most one service is run on a specific port.
For example, it is not possible to start a MAVLink instance on a specific serial device, and then launch a driver that uses the same serial device.
:::warning
At time of writing there is no user feedback about conflicting ports.
:::
<a id="default_port_mapping"></a>
## Default Serial Port Configuration
:::tip
These port mappings can be disabled by setting the associated configuration parameter to _Disabled_.
:::
The following ports are commonly mapped to specific functions on all boards:
- `GPS 1` is configured as a GPS port (using [GPS_1_CONFIG](../advanced_config/parameter_reference.md#GPS_1_CONFIG)).
The default baud rate is set in the [gps driver](../modules/modules_driver.md#gps) by the value of [SER_GPS1_BAUD](../advanced_config/parameter_reference.md#SER_GPS1_BAUD), which has a default rate of _Auto_.
With this setting a GPS will automatically detect the baudrate — except for the Trimble MB-Two, which you will need to explicitly set to 115200 baud rate.
- `RC IN` is configured as an RC input (using [RC_PORT_CONFIG](../advanced_config/parameter_reference.md#RC_PORT_CONFIG)).
- `TELEM 1` is configured as a MAVLink serial port suitable for connection to a GCS via a [telemetry module](../telemetry/index.md).
The configuration uses [MAV_0_CONFIG](../advanced_config/parameter_reference.md#MAV_0_CONFIG) to set the port, [MAV_0_RATE](../advanced_config/parameter_reference.md#MAV_0_RATE) to set the baud rate to 57600, and [MAV_0_MODE](../advanced_config/parameter_reference.md#MAV_1_MODE) to set the messages streamed to "Normal".
For more information see: [MAVLink Peripherals (OSD/GCS/Companion Computers/etc.)](../peripherals/mavlink_peripherals.md).
- `TELEM 2` is configured by default as a MAVLink serial port suitable for connection to an Onboard/Companion computer via a wired connection.
The configuration uses [MAV_1_CONFIG](../advanced_config/parameter_reference.md#MAV_1_CONFIG) to set the port, [MAV_1_RATE](../advanced_config/parameter_reference.md#MAV_1_RATE) to set the baud rate, and [MAV_1_MODE](../advanced_config/parameter_reference.md#MAV_2_MODE) to set the messages streamed to "Onboard".
For more information see: [MAVLink Peripherals (OSD/GCS/Companion Computers/etc.)](../peripherals/mavlink_peripherals.md).
- `Ethernet` is mapped as a MAVLink port on Pixhawk devices that have an Ethernet port.
The configuration uses [MAV_2_CONFIG](../advanced_config/parameter_reference.md#MAV_2_CONFIG) and appropriate settings for the UDP port etc.
For more information see [PX4 Ethernet Setup > PX4 MAVLink Serial Port Configuration](../advanced_config/ethernet_setup.md#px4-mavlink-serial-port-configuration) and [MAVLink Peripherals (OSD/GCS/Companion Computers/etc.)](../peripherals/mavlink_peripherals.md).
- `USB-C` (the USB-C port normally used for connecting to QGroundControl)
This is configured by default as a MAVLink port the onboard profile (for companion computers).
The configuration for MAVLink is unique to this port (it doesn't use the `MAV_X_CONFIG` parameters).
- [SYS_USB_AUTO](../advanced_config/parameter_reference.md#SYS_USB_AUTO) sets whether the port is set to no partiular protocol, autodetects the protocol, or sets the comms link to MAVLink.
- [USB_MAV_MODE](../advanced_config/parameter_reference.md#USB_MAV_MODE) sets the MAVLink profile that is used if MAVLink is set or detected.
Other ports generally have no assigned functions by default (are disabled).
## Troubleshooting
<a id="parameter_not_in_firmware"></a>
### Configuration Parameter Missing from _QGroundControl_
_QGroundControl_ only displays the parameters for services/drivers that are present in firmware.
If a parameter is missing, then you may need to add it in firmware.
::: info
PX4 firmware includes most drivers by default on [Pixhawk-series](../flight_controller/pixhawk_series.md) boards.
Flash-limited boards may comment out/omit the driver (at time of writing this only affects boards based on FMUv2).
:::
You can include the missing driver in firmware by enabling the driver in the **default.px4board** config file that corresponds to the [board](https://github.com/PX4/PX4-Autopilot/tree/main/boards/px4) you want to build for.
For example, to enable the SRF02 driver, you would a the following line to the px4board.
```
CONFIG_DRIVERS_DISTANCE_SENSOR_SRF02=y
```
An easier method would be using boardconfig which launches a GUI where you can easily search, disable and enable modules.
To launch boardconfig type:
```
make <vendor>_<board>_<label> boardconfig
```
You will then need to build the firmware for your platform, as described in [Building PX4 Software](../dev_setup/building_px4.md).
## Further Information
- [MAVLink Peripherals (OSD/GCS/Companion Computers/etc.)](../peripherals/mavlink_peripherals.md)
- [PX4 Ethernet Setup > PX4 MAVLink Serial Port Configuration](../advanced_config/ethernet_setup.md#px4-mavlink-serial-port-configuration)
- [Serial Port Mapping](../hardware/serial_port_mapping.md)
docs/en/peripherals/uavcan_escs.md
+1
View File
@@ -0,0 +1 @@
<Redirect to="../dronecan/escs" />
docs/en/peripherals/vertiq.md
+49
View File
@@ -0,0 +1,49 @@
# Vertiq All-In-One Motor/ESC Modules
Vertiq makes high performance propulsion systems for commercial and defense UAS.
The core design consists of a lightweight, tightly integrated motor and ESC with an embedded position sensor.
With closed loop velocity control for the fastest response times available, class leading efficiency, no startup and reverse jitter allowing low speed control and smooth reversibility, and a built in "stow" controller for smoothly placing idle propellers in a preferred direction, Vertiq's modules have significant advantages over other ESCs.
![Vertiq Module Lineup](../../assets/peripherals/esc_vertiq/vertiq_esc_lineup.jpg)
All Vertiq modules support traditional [PWM input, DShot, OneShot, and Multishot communication protocols](https://iqmotion.readthedocs.io/en/latest/communication_protocols/hobby_protocol.html). Vertiq's larger modules also support [DroneCAN control](https://iqmotion.readthedocs.io/en/latest/communication_protocols/dronecan_protocol.html).
## Where to Buy
Purchasing information can be found on the [Vertiq website](https://www.vertiq.co/).
## Hardware Setup
### Wiring
Connecting your Vertiq module to a PWM output from your flight controller or DroneCAN bus will vary depending on your model.
Please see the product data sheets for wiring information.
All Vertiq datasheets can be found at [vertiq.co](https://www.vertiq.co/).
## Firmware Setup
The best tool to configure your Vertiq module is Vertiq's IQ Control Center application.
You can find instructions for installation in [Getting Started with Speed Modules Using IQ Control Center](https://iqmotion.readthedocs.io/en/latest/control_center_docs/speed_module_getting_started.html).
To get started with traditional PWM input or DShot with your flight controller, please see [PWM and DSHOT Control with a Flight Controller](https://iqmotion.readthedocs.io/en/latest/tutorials/pwm_control_flight_controller.html).
To get started with DroneCAN with your flight controller, please see [DroneCAN Integration with a PX4 Flight Controller](https://iqmotion.readthedocs.io/en/latest/tutorials/dronecan_flight_controller.html).
## Flight Controller Setup
### DroneCAN Configuration
Instructions for integrating the motor/ESC using with DroneCAN can be found in [Flight Controller Configuration](https://iqmotion.readthedocs.io/en/latest/tutorials/dronecan_flight_controller.html#dronecan-integration-with-a-px4-flight-controller) (in _DroneCAN Integration with a PX4 Flight Controller_).
These instructions walk you through setting the correct parameters for enabling the flight controller's DroneCAN drivers, setting the correct configuration parameters for communication with Vertiq modules on the DroneCAN bus, ESC configuration, and testing that your flight controller can properly control your modules over DroneCAN.
### DShot/PWM Configuration
Instructions for integrating the motor/ESC using PWM and DShot can be found in [PWM and DShot Control with a Flight Controller](https://iqmotion.readthedocs.io/en/latest/tutorials/pwm_control_flight_controller.html).
DShot is recommended.
## Further Information
- <https://www.vertiq.co/> — Learn more about Vertiq modules
- [Vertiq Documentation](https://iqmotion.readthedocs.io/en/latest/index.html) — Additional information about configuring your Vertiq module
docs/en/peripherals/vesc.md
+57
View File
@@ -0,0 +1,57 @@
# VESC ESCs (DroneCAN)
The [VESC project](https://vesc-project.com/) is a fully open source hardware and software design for advanced FOC motor controllers.
While it can be controlled using traditional PWM input, it also supports being connected over CAN bus using [DroneCAN](../dronecan/index.md).
## Where to Buy
[Vesc Project > Hardware](https://vesc-project.com/Hardware)
## Hardware Setup
### Wiring
ESCs are connected to the CAN bus using the VESC CAN connector. Note that this is _not_ the Pixhawk standard 4 pin JST GH connector. For more information, refer to the [CAN Wiring](../can/index.md#wiring) instructions. ESC order does not matter.
## Firmware Setup
The preferred tool for motor enumeration is the [VESC tool](https://vesc-project.com/vesc_tool).
In addition to the normal motor configuration that you will have to setup in the VESC tool, you will also need to properly setup the app configuration.
The recommended app setup is as follows:
| Parameter | Option |
| ----------------------- | ---------------------- |
| App to use | `No App` |
| VESC ID | `1,2,...` |
| Can Status Message Mode | `CAN_STATUS_1_2_3_4_5` |
| CAN Baud Rate | `CAN_BAUD_500K` |
| CAN Mode | `UAVCAN` |
| UAVCAN ESC Index | `0,1,...` |
VESC ID should have the same motor numbering as in PX4 convention, starting at `1` for top-right motor, `2` for bottom-left motor etc.
However the `UAVCAN ESC Index` starts from `0`, and as such it is always one index lower than the `VESC ID`.
For example, in a quadcopter the bottom left motor will have `VESC ID = 2` and `UAVCAN ESC Index = 1`.
Finally the `CAN Baud Rate` must match the value set in [UAVCAN_BITRATE](../advanced_config/parameter_reference.md#UAVCAN_BITRATE).
## Flight Controller Setup
### Enable DroneCAN
Connect the ESCs to the Pixhawk CAN bus. Power up the entire vehicle using a battery or power supply (not just the flight controller over USB) and enable the DroneCAN driver by setting the parameter [UAVCAN_ENABLE](../advanced_config/parameter_reference.md#UAVCAN_ENABLE) to `3` to enable both dynamic node ID allocation and DroneCAN ESC output.
### PX4 Configuration
Assign motors to outputs using the [Acutator](../config/actuators.md#actuator-testing) configuration screen.
<!-- removed as there is no info for it in linked doc -->
<!--
## Troubleshooting
See DroneCAN Troubleshooting - (index.md#troubleshooting).
-->
## Further Information
- [VESC Project ESCs](https://vesc-project.com/)
- [Benjamin Vedder's blog](http://vedder.se) (project owner)