mirror of
https://github.com/PX4/PX4-Autopilot.git
synced 2026-05-26 09:26:25 +08:00
Move PX4 Guide source into /docs (#24490)
* 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
GitHub
@@ -0,0 +1,55 @@
|
||||
# I2C Bus (Development Overview)
|
||||
|
||||
I2C is a packet-switched serial communication protocol that allows multiple master devices to connect to multiple slave devices using only 2 wires per connection.
|
||||
It is intended for attaching lower-speed peripheral ICs to processors and microcontrollers in short-distance, intra-board communication.
|
||||
|
||||
Pixhawk/PX4 support it for:
|
||||
* Connecting off board components that require higher data rates than provided by a strict serial UART, such as rangefinders.
|
||||
* Compatibility with peripheral devices that only support I2C.
|
||||
* Allowing multiple devices to attach to a single bus (useful for conserving ports).
|
||||
For example, LEDs, Compass, rangefinders etc.
|
||||
|
||||
::: info
|
||||
The page [Hardware > I2C Peripherals](../sensor_bus/i2c_general.md) contains information about how to _use_ (rather than integrate) I2C peripherals and solve common setup problems.
|
||||
:::
|
||||
|
||||
:::tip
|
||||
IMUs (accelerometers/gyroscopes) should not be attached via I2C (typically the [SPI](https://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus) bus is used).
|
||||
The bus is not fast enough even with a single device attached to allow vibration filtering (for instance), and the performance degrades further with every additional device on the bus.
|
||||
:::
|
||||
|
||||
## Integrating I2C Devices
|
||||
|
||||
Drivers should `#include <drivers/device/i2c.h>` and then provide an implementation of the abstract base class `I2C` defined in **I2C.hpp** for the target hardware (i.e. for NuttX [here](https://github.com/PX4/PX4-Autopilot/blob/main/src/lib/drivers/device/nuttx/I2C.hpp)).
|
||||
|
||||
A small number of drivers will also need to include headers for their type of device (**drv_*.h**) in [/src/drivers/](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers) - e.g. [drv_led.h](https://github.com/PX4/PX4-Autopilot/blob/main/src/drivers/drv_led.h).
|
||||
|
||||
To include a driver in firmware you must add the driver to the board-specific cmake file that corresponds to the target you want to build for.
|
||||
You can do this for a single driver:
|
||||
```
|
||||
CONFIG_DRIVERS_DISTANCE_SENSOR_LIGHTWARE_LASER_I2C=y
|
||||
```
|
||||
|
||||
You can also include all drivers of a particular type.
|
||||
```
|
||||
CONFIG_COMMON_DISTANCE_SENSOR=y
|
||||
```
|
||||
|
||||
:::tip
|
||||
For example, you can see/search for `CONFIG_DRIVERS_DISTANCE_SENSOR_LIGHTWARE_LASER_I2C` in the [px4_fmu-v4_default](https://github.com/PX4/PX4-Autopilot/blob/main/boards/px4/fmu-v4/default.px4board) configuration.
|
||||
:::
|
||||
|
||||
## I2C Driver Examples
|
||||
|
||||
To find I2C driver examples, search for **i2c.h** in [/src/drivers/](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers).
|
||||
|
||||
Just a few examples are:
|
||||
* [drivers/distance_sensor/lightware_laser_i2c](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/distance_sensor/lightware_laser_i2c) - I2C driver for [Lightware SF1XX LIDAR](../sensor/sfxx_lidar.md).
|
||||
* [drivers/distance_sensor/lightware_laser_serial](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/distance_sensor/lightware_laser_serial) - Serial driver for [Lightware SF1XX LIDAR](../sensor/sfxx_lidar.md).
|
||||
* [drivers/ms5611](https://github.com/PX4/PX4-Autopilot/tree/main/src/drivers/barometer/ms5611) - I2C Driver for the MS5611 and MS6507 barometric pressure sensor connected via I2C (or SPI).
|
||||
|
||||
## Further Information
|
||||
|
||||
* [I2C](https://en.wikipedia.org/wiki/I%C2%B2C) (Wikipedia)
|
||||
* [I2C Comparative Overview](https://learn.sparkfun.com/tutorials/i2c) (learn.sparkfun.com)
|
||||
* [Driver Framework](../middleware/drivers.md)
|
||||
@@ -0,0 +1,123 @@
|
||||
# I2C Bus Peripherals
|
||||
|
||||
[I2C](https://en.wikipedia.org/wiki/I2C) is a serial communication protocol that is commonly used (at least on smaller drones), for connecting peripheral components like rangefinders, LEDs, Compass, etc.
|
||||
|
||||
It is recommended for:
|
||||
|
||||
* Connecting offboard components that require low bandwidth and low latency communication, e.g. [rangefinders](../sensor/rangefinders.md), [magnetometers](../gps_compass/magnetometer.md), [airspeed sensors](../sensor/airspeed.md) and [tachometers](../sensor/tachometers.md) .
|
||||
* Compatibility with peripheral devices that only support I2C.
|
||||
* Allowing multiple devices to attach to a single bus, which is useful for conserving ports.
|
||||
|
||||
I2C allows multiple master devices to connect to multiple slave devices using only 2 wires per connection (SDA, SCL).
|
||||
in theory a bus can support 128 devices, each accessed via its unique address.
|
||||
|
||||
::: info
|
||||
UAVCAN would normally be preferred where higher data rates are required, and on larger vehicles where sensors are be mounted further from the flight controller.
|
||||
:::
|
||||
|
||||
|
||||
## Wiring
|
||||
|
||||
I2C uses a pair of wires: SDA (serial data) and SCL (serial clock).
|
||||
The bus is of open-drain type, meaning that devices ground the data line.
|
||||
It uses a pullup resistor to push it to `log.1` (idle state) - every wire has it usually located on the bus terminating devices.
|
||||
One bus can connect to multiple I2C devices.
|
||||
The individual devices are connected without any crossing.
|
||||
|
||||
For connection (according to dronecode standard) 4-wire cables equipped with JST-GH connectors are used.
|
||||
To ensure reliable communication and to reduce crosstalk it is advised to apply recommendations concerning [cable twisting](../assembly/cable_wiring.md#i2c-cables) and pullup resistors placement.
|
||||
|
||||
|
||||
|
||||
|
||||
## Checking the Bus and Device Status
|
||||
|
||||
A useful tool for bus analysis is [i2cdetect](../modules/modules_command.md#i2cdetect).
|
||||
This lists available I2C devices by their addresses.
|
||||
It can be used to find out if a device on the bus is available and if the autopilot can communicate with it.
|
||||
|
||||
The tool can be run in the PX4 terminal with the following command:
|
||||
|
||||
```
|
||||
i2cdetect -b 1
|
||||
```
|
||||
where the bus number is specified after `-b` parameter
|
||||
|
||||
|
||||
## Common problems
|
||||
|
||||
### Address Clashes
|
||||
|
||||
If two I2C devices on a bus have the same ID there will be a clash, and neither device will not work properly (or at all).
|
||||
This usually occurs because a user needs to attach two sensors of the same type to the bus, but may also happen if devices use duplicate addresses by default.
|
||||
|
||||
Particular I2C devices may allow you to select a new address for one of the devices to avoid the clash.
|
||||
Some devices do not support this option, or do not have broad options for the addresses that can be used (i.e. cannot be used to avoid a clash).
|
||||
|
||||
If you can't change the addresses, one option is to use an [I2C Address Translator](#i2c-address-translators).
|
||||
|
||||
### Insufficient Transfer Capacity
|
||||
|
||||
The bandwidth available for each individual device generally decreases as more devices are added. The exact decrease depends on the bandwidth used by each individual device. Therefore it is possible to connect many low bandwidth devices, like [tachometers](../sensor/tachometers.md).
|
||||
If too many devices are added, it can cause transmission errors and network unreliability.
|
||||
|
||||
There are several ways to reduce the problem:
|
||||
* Dividing the devices into groups, each with approximately the same number of devices and connecting each group to one autopilot port
|
||||
* Increase bus speed limit (usually set to 100kHz for external I2C bus)
|
||||
|
||||
### Excessive Wiring Capacitance
|
||||
|
||||
The electrical capacity of bus wiring increases as more devices/wires are added. The exact decrease depends on total length of bus wiring and wiring specific capacitance.
|
||||
The problem can be analyzed using an oscilloscope, where we see that the edges of SDA/SCL signals are no longer sharp.
|
||||
|
||||
There are several ways to reduce the problem:
|
||||
* Dividing the devices into groups, each with approximately the same number of devices and connecting each group to one autopilot port
|
||||
* Using the shortest and the highest quality I2C cables possible
|
||||
* Separating the devices with a weak open-drain driver to smaller bus with lower capacitance
|
||||
* [I2C Bus Accelerators](#i2c-bus-accelerators)
|
||||
|
||||
## I2C Bus Accelerators
|
||||
|
||||
I2C bus accelerators are separate circuits that can be used to support longer wiring length on an I2C bus.
|
||||
They work by physically dividing an I2C network into 2 parts and using their own transistors to amplify I2C signals.
|
||||
|
||||
Available accelerators include:
|
||||
- [Thunderfly TFI2CEXT01](https://github.com/ThunderFly-aerospace/TFI2CEXT01):
|
||||
|
||||
- This has Dronecode connectors and is hence very easy to add to a Pixhawk I2C setup.
|
||||
- The module has no settings (it works out of the box).
|
||||
|
||||
|
||||
## I2C Address Translators
|
||||
|
||||
I2C Address Translators can be used to prevent I2C address clashes in systems where there is no other way to assign unique addresses.
|
||||
The work by listening for I2C communication and transforming the address when a slave device is called (according to a preset algorithm).
|
||||
|
||||
Supported I2C Address Translators include:
|
||||
|
||||
- [Thunderfly TFI2CADT01](../sensor_bus/translator_tfi2cadt.md)
|
||||
|
||||
|
||||
## I2C Bus Splitters
|
||||
|
||||
I2C Bus Splitters are circuit boards that split the I2C port on your flight controller into multiple ports.
|
||||
They are useful if you want to use multiple I2C peripherals on a flight controller that has only one I2C port (or too few), such as an airspeed sensor and a distance sensor.
|
||||
|
||||
You can find an appropriate board using an internet search.
|
||||
|
||||
## I2C Level Converter
|
||||
|
||||
Some I2C devices have 5V on the data lines, while the Pixhawk connector standard port expects these lines to be 3.3 V.
|
||||
You can use an I2C level converter to connect 5V devices to a Pixhawk I2C port.
|
||||
|
||||
You can find an appropriate covnerter using an internet search.
|
||||
|
||||
## I2C Development
|
||||
|
||||
Software development for I2C devices is described in [I2C Bus (Development Overview)](../sensor_bus/i2c_development.md).
|
||||
|
||||
## Further Information
|
||||
|
||||
* [I2C](https://en.wikipedia.org/wiki/I%C2%B2C) (Wikipedia)
|
||||
* [I2C Comparative Overview](https://learn.sparkfun.com/tutorials/i2c) (learn.sparkfun.com)
|
||||
* [Driver Framework](../middleware/drivers.md)
|
||||
@@ -0,0 +1,4 @@
|
||||
# Sensor and Actuator I/O
|
||||
|
||||
This section contains topics about integrating sensors and actuators into PX4.
|
||||
It covers both sensor buses ([I2C](../sensor_bus/i2c_general.md), [CAN](../can/index.md), [UART](../uart/index.md), SPI) and also the main PWM ports.
|
||||
@@ -0,0 +1,66 @@
|
||||
# TFI2CADT01 - I²C Address Translator
|
||||
|
||||
[TFI2CADT01](https://github.com/ThunderFly-aerospace/TFI2CADT01) is an address translator module that is compatible with Pixhawk and PX4.
|
||||
|
||||
Address translation allows multiple I2C devices with the same address to coexist on an I2C network.
|
||||
The module may be needed if using several devices that have the same hard-coded address.
|
||||
|
||||
The module has an input and an output side.
|
||||
A sensor is connected to the master device on one side.
|
||||
On the output side sensors, whose addresses are to be translated, can be connected.
|
||||
The module contains two pairs of connectors, each pair responsible for different translations.
|
||||
|
||||
|
||||
|
||||
::: info
|
||||
[TFI2CADT01](https://github.com/ThunderFly-aerospace/TFI2CADT01) is designed as open-source hardware with GPLv3 license.
|
||||
It is commercially available from [ThunderFly](https://www.thunderfly.cz/) company or from [Tindie eshop](https://www.tindie.com/products/thunderfly/tfi2cadt01-i2c-address-translator/).
|
||||
:::
|
||||
|
||||
## Address Translation Method
|
||||
|
||||
TFI2CADT01 performs an XOR operation on the called address.
|
||||
Therefore, a new device address can be found by taking the original address and applying an XOR operation with the value specified on the module.
|
||||
By default, the output 1 performs XOR with 0x08 value and the second port with 0x78.
|
||||
By short-circuiting the solder jumper you can change the XOR value to 0x0f for the first and 0x7f for the second port.
|
||||
|
||||
If you need your own value for address translation, changing the configuration resistors makes it possible to set any XOR value.
|
||||
|
||||
## Example of Use
|
||||
|
||||
The tachometer sensor [TFRPM01](../sensor/thunderfly_tachometer.md) can be set to two different addresses using a solder jumper.
|
||||
If the autopilot has three buses, only 6 sensors can be connected and no bus remains free (2 available addresses * 3 I2C ports).
|
||||
In some multicopters or VTOL solutions, there is a need to measure the RPM of 8 or more elements.
|
||||
The [TFI2CADT01](https://www.tindie.com/products/thunderfly/tfi2cadt01-i2c-address-translator/) is highly recommended in this case.
|
||||
|
||||
|
||||
|
||||
The following scheme shows how to connect 6 TFRPM01 to one autopilot bus.
|
||||
By adding another TFI2CADT01, 4 more devices can be connected to the same bus.
|
||||
|
||||
[](https://mermaid-js.github.io/mermaid-live-editor/edit#pako:eNptkd9rwjAQx_-VcE8dtJB2ukEfBLEWfJCJy8CHvgRznQH7gzSBDfF_33VZB2oCyf3I576XcBc4dgohh08j-xMTRdUyWuX2I6LNErY7zJh0tuv1ubNP_7csSRZsudlHS22GHlGxAduhM3fEfrdNI1GS4emK8a85fwSyGyC9A0S5yVbrg_DZKfLtCxH9JsjhaU7VvI7pfK3_NCg_NXmO3pwl5uYt9D0yAXoWoFNP4yM9H-kspJ0FtF8CdObpURtiaNA0UisaymWsrsCesMEKcnIV1tKdbQVVeyXU9UpaXCttOwO5NQ5jGKf1_t0ep9gzhZY04sYnrz9BI4mU)
|
||||
|
||||
|
||||
<!-- original mermaid graph
|
||||
graph TD
|
||||
FMU(FMU - PX4 autopilot)
|
||||
FMU -- > AIR(Airspeed sensor)
|
||||
FMU -- > RPM1(TFRPM01C 0x50)
|
||||
FMU -- > RPM2(TFRPM01C 0x51)
|
||||
FMU -- > TFI2CEXT
|
||||
TFI2CEXT -- > ADT(TFI2CADT01: 0x0f, 0x7f)
|
||||
ADT -- > RPM3(Out1: TFRPM01C 0x50 - 0x5f)
|
||||
ADT -- > RPM4(Out1: TFRPM01C 0x51 - 0x5e)
|
||||
ADT -- > RPM5(Out2: TFRPM01C 0x50 - 0x2f)
|
||||
ADT -- > RPM6(Out2: TFRPM01C 0x52 - 0x2e)
|
||||
-->
|
||||
|
||||
|
||||
::: info
|
||||
TFI2CADT01 does not contain any I2C buffer or accelerator.
|
||||
As it adds additional capacitance on the bus, we advise combining it with some bus booster, e.g. [TFI2CEXT01](https://github.com/ThunderFly-aerospace/TFI2CEXT01).
|
||||
:::
|
||||
|
||||
### Other Resources
|
||||
|
||||
* Datasheet of [LTC4317](https://www.analog.com/media/en/technical-documentation/data-sheets/4317fa.pdf)
|
||||
Reference in New Issue
Block a user