diff --git a/docs/ko/SUMMARY.md b/docs/ko/SUMMARY.md index 468fe2206c..300979c54d 100644 --- a/docs/ko/SUMMARY.md +++ b/docs/ko/SUMMARY.md @@ -315,15 +315,17 @@ - [ADSB/FLARM (트래픽 회피)](config/actuators.md) - [ESC 보정](advanced_config/esc_calibration.md) - [ESC와 모터](peripherals/esc_motors.md) + - [ESC Protocols](esc/esc_protocols.md) - [PWM ESC와 서보](peripherals/pwm_escs_and_servo.md) - [DShot ESCs](peripherals/dshot.md) - [OneShot ESCs and Servos](peripherals/oneshot.md) - [DroneCAN ESCs](dronecan/escs.md) - - [Zubax Telega](dronecan/zubax_telega.md) - [PX4 Sapog ESC Firmware](dronecan/sapog.md) - - [Holybro Kotleta](dronecan/holybro_kotleta.md) - - [Vertiq](peripherals/vertiq.md) - - [VESC](peripherals/vesc.md) + - [ARK 4IN1 ESC](esc/ark_4in1_esc.md) + - [Holybro Kotleta](dronecan/holybro_kotleta.md) + - [Vertiq Motor/ESC Modules](peripherals/vertiq.md) + - [VESC Project ESCs](peripherals/vesc.md) + - [Zubax Telega ESCs](dronecan/zubax_telega.md) - [Radio Control (RC)](getting_started/rc_transmitter_receiver.md) - [무선 조종기 설정](config/radio.md) @@ -519,6 +521,7 @@ - [PPS Time Synchronization](advanced/pps_time_sync.md) - [미들웨어](middleware/index.md) - [uORB 메시지 전송](middleware/uorb.md) + - [uORB Docs Standard](uorb/uorb_documentation.md) - [uORB 그라프](middleware/uorb_graph.md) - [uORB Message Reference](msg_docs/index.md) - [Versioned](msg_docs/versioned_messages.md) @@ -581,6 +584,7 @@ - [DebugKeyValue](msg_docs/DebugKeyValue.md) - [DebugValue](msg_docs/DebugValue.md) - [DebugVect](msg_docs/DebugVect.md) + - [DeviceInformation](msg_docs/DeviceInformation.md) - [DifferentialPressure](msg_docs/DifferentialPressure.md) - [DistanceSensor](msg_docs/DistanceSensor.md) - [DistanceSensorModeChangeRequest](msg_docs/DistanceSensorModeChangeRequest.md) diff --git a/docs/ko/advanced_config/ethernet_setup.md b/docs/ko/advanced_config/ethernet_setup.md index ab0a88e48b..0b92e9d940 100644 --- a/docs/ko/advanced_config/ethernet_setup.md +++ b/docs/ko/advanced_config/ethernet_setup.md @@ -25,6 +25,7 @@ It may also be supported on other boards. Supported flight controllers include: +- [ARK Electronics ARKV6X](../flight_controller/ark_v6x.md) - [CUAV Pixhawk V6X](../flight_controller/cuav_pixhawk_v6x.md) - [Holybro Pixhawk 5X](../flight_controller/pixhawk5x.md) - [Holybro Pixhawk 6X](../flight_controller/pixhawk6x.md) diff --git a/docs/ko/assembly/_assembly.md b/docs/ko/assembly/_assembly.md index 496741776c..555111defd 100644 --- a/docs/ko/assembly/_assembly.md +++ b/docs/ko/assembly/_assembly.md @@ -285,7 +285,7 @@ A particular vehicle might have more/fewer motors and actuators, but the wiring The following sections explain each part in more detail. :::tip -If you're using [DroneCAN ESC](../peripherals/esc_motors.md#dronecan) the control signals will be connected to the CAN BUS instead of the PWM outputs as shown. +If you're using [DroneCAN ESC](../dronecan/escs.md) the control signals will be connected to the CAN BUS instead of the PWM outputs as shown. ::: ### Flight Controller Power @@ -426,7 +426,6 @@ They recommend sensors, power systems, and other components from the same manufa - [Drone Components & Parts](../getting_started/px4_basic_concepts.md#drone-components-parts) (Basic Concepts) - [Payloads](../getting_started/px4_basic_concepts.md#payloads) (Basic Concepts) - [Hardware Selection & Setup](../hardware/drone_parts.md) — information about connecting and configuring specific flight controllers, sensors and other peripherals (e.g. airspeed sensor for planes). - - [Mounting the Flight Controller](../assembly/mount_and_orient_controller.md) - [Vibration Isolation](../assembly/vibration_isolation.md) - [Mounting a Compass](../assembly/mount_gps_compass.md) diff --git a/docs/ko/can/index.md b/docs/ko/can/index.md index 137f639189..ee516e9c6c 100644 --- a/docs/ko/can/index.md +++ b/docs/ko/can/index.md @@ -1,7 +1,13 @@ -# CAN +# CAN (DroneCAN & Cyphal) [Controller Area Network (CAN)](https://en.wikipedia.org/wiki/CAN_bus) is a robust wired network that allows drone components such as flight controller, ESCs, sensors, and other peripherals, to communicate with each other. -Because it is designed to be democratic and uses differential signaling, it is very robust even over longer cable lengths (on large vehicles), and avoids a single point of failure. + +It is particularly recommended on larger vehicles. + +## 개요 + +CAN it is designed to be democratic and uses differential signaling. +For this reason it is very robust even over longer cable lengths (on large vehicles), and avoids a single point of failure. CAN also allows status feedback from peripherals and convenient firmware upgrades over the bus. PX4 supports two software protocols for communicating with CAN devices: @@ -18,29 +24,36 @@ In 2022 the project split into two: the original version of UAVCAN (UAVCAN v0) w The differences between the two protocols are outlined in [Cyphal vs. DroneCAN](https://forum.opencyphal.org/t/cyphal-vs-dronecan/1814). ::: -:::warning PX4 does not support other CAN software protocols for drones such as KDECAN (at time of writing). -::: ## 배선 The wiring for CAN networks is the same for both DroneCAN and Cyphal/CAN (in fact, for all CAN networks). -Devices are connected in a chain in any order. +Devices within a network are connected in a _daisy-chain_ in any order (this differs from UARTs peripherals, where you attach just one component per port). + +:::warning +Don't connect each CAN peripheral to a separate CAN port! +Unlike UARTs, CAN peripherals are designed to be daisy chained, with additional ports such as `CAN2` used for [redundancy](redundancy). +::: + At either end of the chain, a 120Ω termination resistor should be connected between the two data lines. Flight controllers and some GNSS modules have built in termination resistors for convenience, thus should be placed at opposite ends of the chain. Otherwise, you can use a termination resistor such as [this one from Zubax Robotics](https://shop.zubax.com/products/uavcan-micro-termination-plug?variant=6007985111069), or solder one yourself if you have access to a JST-GH crimper. The following diagram shows an example of a CAN bus connecting a flight controller to 4 CAN ESCs and a GNSS. +It includes a redundant bus connected to `CAN 2`. ![CAN Wiring](../../assets/can/uavcan_wiring.svg) The diagram does not show any power wiring. Refer to your manufacturer instructions to confirm whether components require separate power or can be powered from the CAN bus itself. +:::info For more information, see [Cyphal/CAN device interconnection](https://wiki.zubax.com/public/cyphal/CyphalCAN-device-interconnection?pageId=2195476) (kb.zubax.com). While the article is written with the Cyphal protocol in mind, it applies equally to DroneCAN hardware and any other CAN setup. For more advanced scenarios, consult with [On CAN bus topology and termination](https://forum.opencyphal.org/t/on-can-bus-topology-and-termination/1685). +::: ### 커넥터 @@ -54,7 +67,30 @@ However, as long as the device firmware supports DroneCAN or Cyphal, it can be u DroneCAN and Cyphal/CAN support using a second (redundant) CAN interface. This is completely optional but increases the robustness of the connection. -All Pixhawk flight controllers come with 2 CAN interfaces; if your peripherals support 2 CAN interfaces as well, it is recommended to wire both up for increased safety. + +Pixhawk flight controllers come with 2 CAN interfaces; if your peripherals support 2 CAN interfaces as well, it is recommended to wire both up for increased safety. + +### Flight Controllers with Multiple CAN Ports + +[Flight Controllers](../flight_controller/index.md) may have up to three independent CAN ports, such as `CAN1`, `CAN2`, `CAN3` (neither DroneCAN or Cyphal support more than three). +Note that you can't have both DroneCAN and Cyphal running on PX4 at the same time. + +:::tip +You only _need_ one CAN port to support an arbitrary number of CAN devices using a particular CAN protocol. +Don't connect each CAN peripheral to a separate CAN port! +::: + +Generally you'll daisy all CAN peripherals off a single port, and if there is more than one CAN port, use the second one for [redundancy](redundancy). +If three are three ports, you might use the remaining network for devices that support another CAN protocol. + +The documentation for your flight controller should indicate which ports are supported/enabled. +At runtime you can check what DroneCAN ports are enabled and their status using the following command on the [MAVLink Shell](../debug/mavlink_shell.md) (or some other console): + +```sh +uavcan status +``` + +Note that you can also check the number of supported CAN interfaces for a board by searching for `CONFIG_BOARD_UAVCAN_INTERFACES` in its [default.px4board](https://github.com/PX4/PX4-Autopilot/blob/main/boards/px4/fmu-v6xrt/default.px4board#) configuration file. ## 펌웨어 diff --git a/docs/ko/config_mc/filter_tuning.md b/docs/ko/config_mc/filter_tuning.md index 665ca9dc33..2a7e2cd406 100644 --- a/docs/ko/config_mc/filter_tuning.md +++ b/docs/ko/config_mc/filter_tuning.md @@ -70,7 +70,7 @@ Airframes with more than two frequency noise spikes typically clean the first tw Dynamic notch filters use ESC RPM feedback and/or the onboard FFT analysis. The ESC RPM feedback is used to track the rotor blade pass frequency and its harmonics, while the FFT analysis can be used to track a frequency of another vibration source, such as a fuel engine. -ESC RPM feedback requires ESCs capable of providing RPM feedback such as [DShot](../peripherals/esc_motors.md#dshot) with telemetry connected, a bidirectional DShot set up ([work in progress](https://github.com/PX4/PX4-Autopilot/pull/23863)), or [UAVCAN/DroneCAN ESCs](../dronecan/escs.md). +ESC RPM feedback requires ESCs capable of providing RPM feedback such as [DShot](../peripherals/dshot.md) with telemetry connected, a bidirectional DShot set up ([work in progress](https://github.com/PX4/PX4-Autopilot/pull/23863)), or [UAVCAN/DroneCAN ESCs](../dronecan/escs.md). Before enabling, make sure that the ESC RPM is correct. You might have to adjust the [pole count of the motors](../advanced_config/parameter_reference.md#MOT_POLE_COUNT). diff --git a/docs/ko/dronecan/ark_flow.md b/docs/ko/dronecan/ark_flow.md index 17766bbdb6..8ce7da3a11 100644 --- a/docs/ko/dronecan/ark_flow.md +++ b/docs/ko/dronecan/ark_flow.md @@ -94,6 +94,7 @@ Set the following parameters in _QGroundControl_: - To optionally disable GPS aiding, set [EKF2_GPS_CTRL](../advanced_config/parameter_reference.md#EKF2_GPS_CTRL) to `0`. - Enable [UAVCAN_SUB_FLOW](../advanced_config/parameter_reference.md#UAVCAN_SUB_FLOW). - Enable [UAVCAN_SUB_RNG](../advanced_config/parameter_reference.md#UAVCAN_SUB_RNG). +- Set [EKF2_RNG_CTRL](../advanced_config/parameter_reference.md#EKF2_RNG_CTRL) to `1`. - Set [EKF2_RNG_A_HMAX](../advanced_config/parameter_reference.md#EKF2_RNG_A_HMAX) to `10`. - Set [EKF2_RNG_QLTY_T](../advanced_config/parameter_reference.md#EKF2_RNG_QLTY_T) to `0.2`. - Set [UAVCAN_RNG_MIN](../advanced_config/parameter_reference.md#UAVCAN_RNG_MIN) to `0.08`. diff --git a/docs/ko/dronecan/ark_flow_mr.md b/docs/ko/dronecan/ark_flow_mr.md index c9e0bbced3..e949b4cfa3 100644 --- a/docs/ko/dronecan/ark_flow_mr.md +++ b/docs/ko/dronecan/ark_flow_mr.md @@ -91,6 +91,7 @@ Set the following parameters in _QGroundControl_: - To optionally disable GPS aiding, set [EKF2_GPS_CTRL](../advanced_config/parameter_reference.md#EKF2_GPS_CTRL) to `0`. - Enable [UAVCAN_SUB_FLOW](../advanced_config/parameter_reference.md#UAVCAN_SUB_FLOW). - Enable [UAVCAN_SUB_RNG](../advanced_config/parameter_reference.md#UAVCAN_SUB_RNG). +- Set [EKF2_RNG_CTRL](../advanced_config/parameter_reference.md#EKF2_RNG_CTRL) to `1`. - Set [EKF2_RNG_A_HMAX](../advanced_config/parameter_reference.md#EKF2_RNG_A_HMAX) to `10`. - Set [EKF2_RNG_QLTY_T](../advanced_config/parameter_reference.md#EKF2_RNG_QLTY_T) to `0.2`. - Set [UAVCAN_RNG_MIN](../advanced_config/parameter_reference.md#UAVCAN_RNG_MIN) to `0.08`. diff --git a/docs/ko/dronecan/escs.md b/docs/ko/dronecan/escs.md index 4d97c7cfd1..6afea8c2e2 100644 --- a/docs/ko/dronecan/escs.md +++ b/docs/ko/dronecan/escs.md @@ -1,7 +1,14 @@ # DroneCAN ESCs PX4 supports DroneCAN compliant ESCs. -For more information, see the following articles for specific hardware/firmware: + +## Supported ESC + +:::info +[Supported ESCs](../peripherals/esc_motors#supported-esc) in _ESCs & Motors_ may include additional devices that are not listed below. +::: + +The following articles have specific hardware/firmware information: - [PX4 Sapog ESC Firmware](sapog.md) - [Holybro Kotleta 20](holybro_kotleta.md) diff --git a/docs/ko/esc/ark_4in1_esc.md b/docs/ko/esc/ark_4in1_esc.md new file mode 100644 index 0000000000..e558bb5668 --- /dev/null +++ b/docs/ko/esc/ark_4in1_esc.md @@ -0,0 +1,65 @@ +# ARK 4IN1 ESC (with/without Connectors) + +4 in 1 Electronic Speed Controller (ESC) that is made in the USA, NDAA compliant, and DIU Blue Framework listed. + +The ESC comes in variants without connectors that you can solder in place, and a variant that has built-in motor and battery connectors (no soldering required). + +![ARK 4IN1 ESC without connectors ](../../assets/hardware/esc/ark/ark_4_in_1_esc.jpg)![ARK 4IN1 ESC with connectors](../../assets/hardware/esc/ark/ark_4_in_1_esc_with_connectors.jpg) + +## 구매처 + +Order this module from: + +- [4IN1 ESC (with connectors)](https://arkelectron.com/product/ark-4in1-esc/) (ARK Electronics - US) +- [ARK Electronics (without connectors)](https://arkelectron.com/product/ark-4in1-esc-cons/) (ARK Electronics US) + +## Hardware Specifications + +- Battery Voltage: 3-8s + - 6V Minimum + - 65V Absolute Maximum + +- Current Rating: 50A Continuous, 75A Burst Per Motor + +- [STM32F0](https://www.st.com/en/microcontrollers-microprocessors/stm32f0-series.html) + +- [AM32 Firmware](https://github.com/am32-firmware/AM32/pull/27) + +- Onboard Current Sensor, Serial Telemetry + - 100V/A + +- Input Protocols + - DShot (300, 600) + - Bi-directional DShot + - KISS Serial Telemetry + - PWM + +- 8 Pin JST-SH Input/Output + +- 10 Pin JST-SH Debug + +- Motor & Battery Connectors (with-connector version) + + - MR30 Connector Limit Per Motor: 30A Continuous, 40A Burst + - Four MR30 Motor Connectors + +- Dimensions (with connectors) + + - Size: 77.00mm x 42.00mm x 9.43mm + - Mounting Pattern: 30.5mm + - Weight: 24g + +- Dimensions (without connectors) + - Size: 43.00mm x 40.50mm x 7.60mm + - Mounting Pattern: 30.5mm + - Weight: 14.5g + +Other + +- Made in the USA +- Open source AM32 firmware +- [DIU Blue Framework Listed](https://www.diu.mil/blue-uas/framework) + +## See Also + +- [ARK 4IN1 ESC CONS](https://docs.arkelectron.com/electronic-speed-controller/ark-4in1-esc) (ARK Docs) diff --git a/docs/ko/esc/esc_protocols.md b/docs/ko/esc/esc_protocols.md new file mode 100644 index 0000000000..930d436de6 --- /dev/null +++ b/docs/ko/esc/esc_protocols.md @@ -0,0 +1,66 @@ +# ESC Protocols + +This topic lists the main [Electronic Speed Controller (ESC)](../peripherals/esc_motors.md) protocols supported by PX4. + +## DShot + +[DShot](../peripherals/dshot.md) is a digital ESC protocol that is highly recommended for vehicles that can benefit from reduced 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 reverse motor spin directions. + +PX4 configuration is done in the [Actuator Configuration](../config/actuators.md). +Selecting a higher rate DShot ESC in the UI results 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 200 Hz. + +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). + +## 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 speed. +The pulse width typically ranges between 1000 μs for zero power and 2000 μs for full power. +The periodic frame rate of the signal depends on the capability of the ESC, and commonly ranges between 50 Hz and 490 Hz (the theoretical maximum being 500 Hz 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 50 Hz 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 pulse widths 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 125 μs to 250 μs 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) diff --git a/docs/ko/middleware/uorb.md b/docs/ko/middleware/uorb.md index 5dab1582fa..1928f9acf5 100644 --- a/docs/ko/middleware/uorb.md +++ b/docs/ko/middleware/uorb.md @@ -280,6 +280,8 @@ For more information see: [Plotting uORB Topic Data in Real Time using PlotJuggl ## See Also +- [uORB Documentation Standard](../uorb/uorb_documentation.md) + - _PX4 uORB Explained_ Blog series - [Part 1](https://px4.io/px4-uorb-explained-part-1/) - [Part 2](https://px4.io/px4-uorb-explained-part-2/) diff --git a/docs/ko/modules/modules_driver.md b/docs/ko/modules/modules_driver.md index 44b77996b8..cbcd7b8448 100644 --- a/docs/ko/modules/modules_driver.md +++ b/docs/ko/modules/modules_driver.md @@ -15,38 +15,6 @@ - [Rpm Sensor](modules_driver_rpm_sensor.md) - [Transponder](modules_driver_transponder.md) -## MCP23009 - -Source: [drivers/gpio/mcp23009](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/gpio/mcp23009) - -### Usage {#MCP23009_usage} - -``` -MCP23009 [arguments...] - Commands: - start - [-I] Internal I2C bus(es) - [-X] External I2C bus(es) - [-b ] board-specific bus (default=all) (external SPI: n-th bus - (default=1)) - [-f ] bus frequency in kHz - [-q] quiet startup (no message if no device found) - [-a ] I2C address - default: 37 - [-D ] Direction - default: 0 - [-O ] Output - default: 0 - [-P ] Pullups - default: 0 - [-U ] Update Interval [ms] - default: 0 - - stop - - status print status info -``` - ## atxxxx Source: [drivers/osd/atxxxx](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/osd/atxxxx) @@ -749,6 +717,40 @@ lsm303agr [arguments...] status print status info ``` +## mcp230xx + +Source: [lib/drivers/mcp_common](https://github.com/PX4/PX4-Autopilot/tree/main/src/lib/drivers/mcp_common) + +### Usage {#mcp230xx_usage} + +``` +mcp230xx [arguments...] + Commands: + start + [-I] Internal I2C bus(es) + [-X] External I2C bus(es) + [-b ] board-specific bus (default=all) (external SPI: n-th bus + (default=1)) + [-f ] bus frequency in kHz + [-q] quiet startup (no message if no device found) + [-a ] I2C address + default: 39 + [-D ] Direction (1=Input, 0=Output) + default: 0 + [-O ] Output + default: 0 + [-P ] Pullups + default: 0 + [-U ] Update Interval [ms] + default: 0 + [-M ] First minor number + default: 0 + + stop + + status print status info +``` + ## mcp9808 Source: [drivers/temperature_sensor/mcp9808](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/temperature_sensor/mcp9808) @@ -899,8 +901,6 @@ fetching the latest mixing result and write them to PCA9685 at its scheduling ti It can do full 12bits output as duty-cycle mode, while also able to output precious pulse width that can be accepted by most ESCs and servos. -The I2C bus and address can be configured via parameters `PCA9685_EN_BUS` and `PCA9685_I2C_ADDR`, or via command line arguments. - ### 예 It is typically started with: diff --git a/docs/ko/modules/modules_system.md b/docs/ko/modules/modules_system.md index 66b946220f..8be479bba8 100644 --- a/docs/ko/modules/modules_system.md +++ b/docs/ko/modules/modules_system.md @@ -127,6 +127,10 @@ commander [arguments...] check Run preflight checks + safety Change prearm safety state + on|off [on] to activate safety, [off] to deactivate safety and allow + control surface movements + arm [-f] Force arming (do not run preflight checks) diff --git a/docs/ko/msg_docs/BatteryStatus.md b/docs/ko/msg_docs/BatteryStatus.md index addd1ae524..ec2c19c59e 100644 --- a/docs/ko/msg_docs/BatteryStatus.md +++ b/docs/ko/msg_docs/BatteryStatus.md @@ -2,7 +2,7 @@ Battery status -Battery status information for up to 4 battery instances. +Battery status information for up to 3 battery instances. These are populated from power module and smart battery device drivers, and one battery updated from MAVLink. Battery instance information is also logged and streamed in MAVLink telemetry. @@ -11,7 +11,7 @@ Battery instance information is also logged and streamed in MAVLink telemetry. ```c # Battery status # -# Battery status information for up to 4 battery instances. +# Battery status information for up to 3 battery instances. # These are populated from power module and smart battery device drivers, and one battery updated from MAVLink. # Battery instance information is also logged and streamed in MAVLink telemetry. @@ -33,9 +33,9 @@ uint8 cell_count # [-] [@invalid 0] Number of cells uint8 source # [@enum SOURCE] Battery source -uint8 SOURCE_POWER_MODULE = 0 # Power module -uint8 SOURCE_EXTERNAL = 1 # External -uint8 SOURCE_ESCS = 2 # ESCs +uint8 SOURCE_POWER_MODULE = 0 # Power module (analog ADC or I2C power monitor) +uint8 SOURCE_EXTERNAL = 1 # External (MAVLink, CAN, or external driver) +uint8 SOURCE_ESCS = 2 # ESCs (via ESC telemetry) uint8 priority # [-] Zero based priority is the connection on the Power Controller V1..Vn AKA BrickN-1 uint16 capacity # [mAh] Capacity of the battery when fully charged diff --git a/docs/ko/msg_docs/BatteryStatusV0.md b/docs/ko/msg_docs/BatteryStatusV0.md index 86500d17a6..cd900a1f17 100644 --- a/docs/ko/msg_docs/BatteryStatusV0.md +++ b/docs/ko/msg_docs/BatteryStatusV0.md @@ -32,9 +32,9 @@ uint8 cell_count # [@invalid 0] Number of cells uint8 source # [@enum SOURCE] Battery source -uint8 SOURCE_POWER_MODULE = 0 # Power module -uint8 SOURCE_EXTERNAL = 1 # External -uint8 SOURCE_ESCS = 2 # ESCs +uint8 SOURCE_POWER_MODULE = 0 # Power module (analog ADC or I2C power monitor) +uint8 SOURCE_EXTERNAL = 1 # External (MAVLink, CAN, or external driver) +uint8 SOURCE_ESCS = 2 # ESCs (via ESC telemetry) uint8 priority # Zero based priority is the connection on the Power Controller V1..Vn AKA BrickN-1 uint16 capacity # [mAh] Capacity of the battery when fully charged diff --git a/docs/ko/msg_docs/DeviceInformation.md b/docs/ko/msg_docs/DeviceInformation.md new file mode 100644 index 0000000000..d415461f94 --- /dev/null +++ b/docs/ko/msg_docs/DeviceInformation.md @@ -0,0 +1,45 @@ +# DeviceInformation (UORB message) + +Device information + +Can be used to uniquely associate a device_id from a sensor topic with a physical device using serial number. +as well as tracking of the used firmware versions on the devices. + +[source file](https://github.com/PX4/PX4-Autopilot/blob/main/msg/DeviceInformation.msg) + +```c +# Device information +# +# Can be used to uniquely associate a device_id from a sensor topic with a physical device using serial number. +# as well as tracking of the used firmware versions on the devices. + +uint64 timestamp # time since system start (microseconds) + +uint8 device_type # [@enum DEVICE_TYPE] Type of the device. Matches MAVLink DEVICE_TYPE enum + +uint8 DEVICE_TYPE_GENERIC = 0 # Generic/unknown sensor +uint8 DEVICE_TYPE_AIRSPEED = 1 # Airspeed sensor +uint8 DEVICE_TYPE_ESC = 2 # ESC +uint8 DEVICE_TYPE_SERVO = 3 # Servo +uint8 DEVICE_TYPE_GPS = 4 # GPS +uint8 DEVICE_TYPE_MAGNETOMETER = 5 # Magnetometer +uint8 DEVICE_TYPE_PARACHUTE = 6 # Parachute +uint8 DEVICE_TYPE_RANGEFINDER = 7 # Rangefinder +uint8 DEVICE_TYPE_WINCH = 8 # Winch +uint8 DEVICE_TYPE_BAROMETER = 9 # Barometer +uint8 DEVICE_TYPE_OPTICAL_FLOW = 10 # Optical flow +uint8 DEVICE_TYPE_ACCELEROMETER = 11 # Accelerometer +uint8 DEVICE_TYPE_GYROSCOPE = 12 # Gyroscope +uint8 DEVICE_TYPE_DIFFERENTIAL_PRESSURE = 13 # Differential pressure +uint8 DEVICE_TYPE_BATTERY = 14 # Battery +uint8 DEVICE_TYPE_HYGROMETER = 15 # Hygrometer + +char[32] vendor_name # Name of the device vendor +char[32] model_name # Name of the device model + +uint32 device_id # [-] [@invalid 0 if not available] Unique device ID for the sensor. Does not change between power cycles. +char[24] firmware_version # [-] [@invalid empty if not available] Firmware version. +char[24] hardware_version # [-] [@invalid empty if not available] Hardware version. +char[33] serial_number # [-] [@invalid empty if not available] Device serial number or unique identifier. + +``` diff --git a/docs/ko/msg_docs/EstimatorStatus.md b/docs/ko/msg_docs/EstimatorStatus.md index 9c24221691..aca77484b9 100644 --- a/docs/ko/msg_docs/EstimatorStatus.md +++ b/docs/ko/msg_docs/EstimatorStatus.md @@ -21,6 +21,7 @@ uint8 GPS_CHECK_FAIL_MAX_VERT_DRIFT = 7 # 7 : maximum allowed vertical position uint8 GPS_CHECK_FAIL_MAX_HORZ_SPD_ERR = 8 # 8 : maximum allowed horizontal speed fail - requires stationary vehicle uint8 GPS_CHECK_FAIL_MAX_VERT_SPD_ERR = 9 # 9 : maximum allowed vertical velocity discrepancy fail uint8 GPS_CHECK_FAIL_SPOOFED = 10 # 10 : GPS signal is spoofed +uint8 GPS_CHECK_FAIL_JAMMED = 11 # 11 : GPS signal is jammed uint64 control_mode_flags # Bitmask to indicate EKF logic state uint8 CS_TILT_ALIGN = 0 # 0 - true if the filter tilt alignment is complete diff --git a/docs/ko/msg_docs/GpioIn.md b/docs/ko/msg_docs/GpioIn.md index 039ed02851..589e7d7841 100644 --- a/docs/ko/msg_docs/GpioIn.md +++ b/docs/ko/msg_docs/GpioIn.md @@ -6,6 +6,7 @@ GPIO mask and state ```c # GPIO mask and state +uint8 MAX_INSTANCES = 8 uint64 timestamp # time since system start (microseconds) uint32 device_id # Device id diff --git a/docs/ko/msg_docs/GpsDump.md b/docs/ko/msg_docs/GpsDump.md index 1f96901671..03910da906 100644 --- a/docs/ko/msg_docs/GpsDump.md +++ b/docs/ko/msg_docs/GpsDump.md @@ -9,11 +9,15 @@ This message is used to dump the raw gps communication to the log. uint64 timestamp # time since system start (microseconds) +uint8 INSTANCE_MAIN = 0 +uint8 INSTANCE_SECONDARY = 1 + uint8 instance # Instance of GNSS receiver +uint32 device_id uint8 len # length of data, MSB bit set = message to the gps device, # clear = message from the device uint8[79] data # data to write to the log -uint8 ORB_QUEUE_LENGTH = 8 +uint8 ORB_QUEUE_LENGTH = 16 ``` diff --git a/docs/ko/msg_docs/VehicleCommand.md b/docs/ko/msg_docs/VehicleCommand.md index 1b1b3ed658..225f680857 100644 --- a/docs/ko/msg_docs/VehicleCommand.md +++ b/docs/ko/msg_docs/VehicleCommand.md @@ -108,6 +108,7 @@ uint16 VEHICLE_CMD_LOGGING_START = 2510 # Start streaming ULog data. uint16 VEHICLE_CMD_LOGGING_STOP = 2511 # Stop streaming ULog data. uint16 VEHICLE_CMD_CONTROL_HIGH_LATENCY = 2600 # Control starting/stopping transmitting data over the high latency link. uint16 VEHICLE_CMD_DO_VTOL_TRANSITION = 3000 # Command VTOL transition. +uint16 VEHICLE_CMD_DO_SET_SAFETY_SWITCH_STATE = 5300 # Command safety on/off. |1 to activate safety, 0 to deactivate safety and allow control surface movements|Unused|Unused|Unused|Unused|Unused|Unused| uint16 VEHICLE_CMD_ARM_AUTHORIZATION_REQUEST = 3001 # Request arm authorization. uint16 VEHICLE_CMD_PAYLOAD_PREPARE_DEPLOY = 30001 # Prepare a payload deployment in the flight plan. uint16 VEHICLE_CMD_PAYLOAD_CONTROL_DEPLOY = 30002 # Control a pre-programmed payload deployment. @@ -187,6 +188,10 @@ int8 ARMING_ACTION_ARM = 1 uint8 GRIPPER_ACTION_RELEASE = 0 uint8 GRIPPER_ACTION_GRAB = 1 +# Used as param1 in DO_SET_SAFETY_SWITCH_STATE command. +uint8 SAFETY_OFF = 0 +uint8 SAFETY_ON = 1 + uint8 ORB_QUEUE_LENGTH = 8 float32 param1 # Parameter 1, as defined by MAVLink uint16 VEHICLE_CMD enum. diff --git a/docs/ko/msg_docs/index.md b/docs/ko/msg_docs/index.md index 6b377bf072..7458c79a24 100644 --- a/docs/ko/msg_docs/index.md +++ b/docs/ko/msg_docs/index.md @@ -105,6 +105,7 @@ Graphs showing how these are used [can be found here](../middleware/uorb_graph.m - [DebugKeyValue](DebugKeyValue.md) - [DebugValue](DebugValue.md) - [DebugVect](DebugVect.md) +- [DeviceInformation](DeviceInformation.md) — Device information - [DifferentialPressure](DifferentialPressure.md) — Differential-pressure (airspeed) sensor - [DistanceSensor](DistanceSensor.md) — DISTANCE_SENSOR message data - [DistanceSensorModeChangeRequest](DistanceSensorModeChangeRequest.md) diff --git a/docs/ko/peripherals/dshot.md b/docs/ko/peripherals/dshot.md index 873ebe3d8a..020bd3a994 100644 --- a/docs/ko/peripherals/dshot.md +++ b/docs/ko/peripherals/dshot.md @@ -11,6 +11,10 @@ DShot is an alternative ESC protocol that has several advantages over [PWM](../p 이 항목에서는 DShot ESC 연결과 설정 방법을 설명합니다. +## Supported ESC + +[ESCs & Motors > Supported ESCs](../peripherals/esc_motors#supported-esc) has a list of supported ESC (check "Protocols" column for DShot ESC). + ## Wiring/Connections {#wiring} DShot ESC are wired the same way as [PWM ESCs](pwm_escs_and_servo.md). diff --git a/docs/ko/peripherals/esc_motors.md b/docs/ko/peripherals/esc_motors.md index 7fdbe37245..12692a3ad6 100644 --- a/docs/ko/peripherals/esc_motors.md +++ b/docs/ko/peripherals/esc_motors.md @@ -3,80 +3,44 @@ 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). +PX4 supports a number of [common protocols](../esc/esc_protocols.md) 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). + +## Supported ESC + +The following list is non-exhaustive. + +| ESC Device | Protocols | Firmwares | 참고 | +| ---------------------------------------------------------------------------------- | ------------------------------------ | ------------------------ | ----------------------------------------------------- | +| [ARK 4IN1 ESC] | [Dshot], [PWM] | [AM32] | Has versions with/without connnectors | +| [Holybro Kotleta 20] | [DroneCAN], [PWM] | [PX4 Sapog ESC Firmware] | | +| [Vertiq Motor & ESC modules] | [Dshot], [OneShot], Multishot, [PWM] | Vertiq firmware | Larger modules support DroneCAN, ESC and Motor in one | +| [RaccoonLab CAN PWM ESC nodes] | [DroneCAN], Cyphal | | Cyphal and DroneCAN notes for PWM ESC | +| [VESC ESCs] | [DroneCAN], [PWM] | VESC project firmware | | +| [Zubax Telega] | [DroneCAN], [PWM] | Telega-based | ESC and Motor in one | + + + +[ARK 4IN1 ESC]: ../esc/ark_4in1_esc.md +[AM32]: https://am32.ca/ +[PX4 Sapog ESC Firmware]: ../dronecan/sapog.md +[VESC ESCs]: ../peripherals/vesc.md +[DroneCAN]: ../dronecan/escs.md +[Dshot]: ../peripherals/dshot.md +[OneShot]: ../peripherals/oneshot.md +[PWM]: ../peripherals/pwm_escs_and_servo.md +[Holybro Kotleta 20]: ../dronecan/holybro_kotleta.md +[Vertiq Motor & ESC modules]: ../peripherals/vertiq.md +[RaccoonLab CAN PWM nodes]: ../dronecan/raccoonlab_nodes.md +[Zubax Telega]: ../dronecan/zubax_telega.md + +## See Also 더 자세한 정보는 다음을 참고하십시오. +- [ESC Protocols](../esc/esc_protocols.md) — overview of main ESC/Servo protocols supported by PX4 - [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). diff --git a/docs/ko/uorb/uorb_documentation.md b/docs/ko/uorb/uorb_documentation.md new file mode 100644 index 0000000000..d056d48860 --- /dev/null +++ b/docs/ko/uorb/uorb_documentation.md @@ -0,0 +1,170 @@ +# uORB Documentation Standard + +This topic demonstrates and explains how to document uORB messages. + +:::info +At time of writing many topics have not been updated. +::: + +## 개요 + +The [AirspeedValidated](../msg_docs/AirspeedValidated.md) message shown below is a good example of a uORB topic that has been documented to the current standard. + +```py +# Validated airspeed +# +# Provides information about airspeed (indicated, true, calibrated) and the source of the data. +# Used by controllers, estimators and for airspeed reporting to operator. + +uint32 MESSAGE_VERSION = 1 + +uint64 timestamp # [us] Time since system start + +float32 indicated_airspeed_m_s # [m/s] [@invalid NaN] Indicated airspeed (IAS) +float32 calibrated_airspeed_m_s # [m/s] [@invalid NaN] Calibrated airspeed (CAS) +float32 true_airspeed_m_s # [m/s] [@invalid NaN] True airspeed (TAS) + +int8 airspeed_source # [@enum SOURCE] Source of currently published airspeed values +int8 SOURCE_DISABLED = -1 # Disabled +int8 SOURCE_GROUND_MINUS_WIND = 0 # Ground speed minus wind +int8 SOURCE_SENSOR_1 = 1 # Sensor 1 +int8 SOURCE_SENSOR_2 = 2 # Sensor 2 +int8 SOURCE_SENSOR_3 = 3 # Sensor 3 +int8 SOURCE_SYNTHETIC = 4 # Synthetic airspeed + +float32 calibrated_ground_minus_wind_m_s # [m/s] [@invalid NaN] CAS calculated from groundspeed - windspeed, where windspeed is estimated based on a zero-sideslip assumption +float32 calibraded_airspeed_synth_m_s # [m/s] [@invalid NaN] Synthetic airspeed +float32 airspeed_derivative_filtered # [m/s^2] Filtered indicated airspeed derivative +float32 throttle_filtered # [-] Filtered fixed-wing throttle +float32 pitch_filtered # [rad] Filtered pitch +``` + +The main things to note are: + +- Documentation is added using formatted uORB comments. + Any text on a line after the `#` character is a comment, except for lines that start with the text `# TOPIC` (which indicates a multi-topic message). +- The message starts with a comment block consisting of short description (mandatory), followed by a longer description and then a space. +- Field and constants almost all have comments. + The comments are added on the same line as the field/constant, separated by one space. +- Fields: + - Comments are all on the same line as the field (extra lines become internal comments). + - Comments start with metadata, such as the units (`[m/s]`, `[rad/s]`) or allowed values (`[@enum SOURCE]`), and can also list invalid values (`[@invalid NaN]`) and allowed ranges (`[@range min, max]`). + - Units are required except for boolean fields or for fields with an enum value. + `[-]` is used to indicate unitless fields. + - Comments follow the metadata after a space. + The line should not be terminated in a full stop. +- Constants: + - Don't have metadata: the description follows the comment marker after one space. + - Some constants, such as `MESSAGE_VERSION`, don't need documentation because they are standardized. + - Constants with the same name prefix are grouped together as enums after the associated field. + +The following sections expand on the allowed formats. + +## Message Description + +Every message should start with a comment block that describes the message: + +```py +# Short description (mandatory) +# +# Longer description for the message if needed. +# Can be multiline, and should have punctuation. +# Should be followed by an empty line. +``` + +This consists of a mandatory short description, optionally followed by an empty comment line, and then a longer description. + +Short description (mandatory): + +- A succinct explanation for the purpose of the message. +- Usually just one line without a terminating full stop. +- Minimally it may just mirror the message name. +- For example, [`AirspeedValidated`](../msg_docs/AirspeedValidated.md) above has the short description `Validated airspeed`. + +Long description (Optional): + +- Additional context required to understand how the message is used. +- In particular this should be anything that can't be inferred from the name, fields or constants, such as the publishers and expected consumers. + It might also cover whether the message is only used for a particular frame type or mode. +- The message is often multiline and contains punctuation. +- May include comment lines that are empty, in order to indicate paragraphs. + +Both short and long descriptions may be multi-line. +Single line descriptions should not include a terminating full stop, but multiline comments should do so. + +The message description block ends at the first non-comment line, which should be an empty line, but might be a field or constant. +Any subsequent comment lines are considered "internal comments". + +### Fields + +A typical field comment looks like this: + +```py +float32 indicated_airspeed_m_s # [m/s] [@invalid NaN] Indicated airspeed (IAS) +``` + +Field comments must all be on the same line as the field, and consist of optional metadata followed by a description: + +- `metadata` (Optional) + - Information about the field units and allowed values: + - `[]` + - The unit of measurement inside square brackets (note, no `@` delineator indicates a unit), such as `[m]` for metres. + - Allowed units include: `m`, `m/s`, `m/s^2`, `rad`, `rad/s`, `rpm`, `V`, `A`, `mA`, `mAh`, `W`, `dBm`, `s`, `ms`, `us`, `Ohm`, `MB`, `Kb/s`, `degC`, `Pa`. + - Units are required unless clearly invalid, such as when the field is a boolean, or is an enum value. + - Unitless values should be specified as `[-]`. + Note though that units are not required for boolean fields or enum fields. + - `[@enum ]` + - The `enum_name` gives the prefix of constant values in the message that can be assigned to the field. + Note that enums in uORB are just a naming convention: they are not explicitly declared. + Multiple enum names allowed for a field indicates a possible error in the field design. + - `[@range , ]` + - The allowed range of the field, specified as a `lower_value` and/or an `upper_value`. + Either value can be omitted to indicate an unbounded upper or lower value. + For example `[@range 0, 3]`, `[@range 5.3, ]`, `[@range , 3]`. + - `[@invalid ]` + - The `value` to set the field to indicate that the field doesn't contain valid data, such as `[@invalid NaN]`. + The `description` is optional, and might be used to indicate the conditions under which data is invalid. + - `[@frame ]` + - The `frame` in which the field is set, such as `[@frame NED]` or `[@frame Body]`. +- `description` + - A concise description of the purpose of the field, and including any important information that can't be inferred from the name! + Use a capital first letter, and omit the full stop if the description is a single sentence. + Multiple sentences may also omit the final full stop. + +### Constants + +Constants follow the documentation conventions as fields except they only have a description (no metadata). +Documentation for a constant might look like this: + +```py +int8 SOURCE_GROUND_MINUS_WIND = 0 # Ground speed minus wind +``` + +Constants are often grouped together following a field as enum values. +Note below how the prefix `SOURCE` for the values is specified as an enum against the _field_. + +```py +int8 airspeed_source # [@enum SOURCE] Source of currently published airspeed values +int8 SOURCE_DISABLED = -1 # Disabled +int8 SOURCE_GROUND_MINUS_WIND = 0 # Ground speed minus wind +... +``` + +A small number of constants have a standardised meaning and do not require documentation. +These are: + +- `ORB_QUEUE_LENGTH` +- `MESSAGE_VERSION` + +### `# TOPICS` + +The prefix `# TOPICS` is used to indicate topic names for multi-topic messages. +For example, the [VehicleGlobalPosition.msg](../msg_docs/VehicleGlobalPosition.md) message definition is used to define the topic ids as shown: + +```text +# TOPICS vehicle_global_position vehicle_global_position_groundtruth external_ins_global_position +# TOPICS estimator_global_position +# TOPICS aux_global_position +``` + +At time of writing there is no format for documenting these.