Add BNO055 9-DOF Absolute Orientation Sensor documentation

content/components/sensor/bno055.md

@@ -0,0 +1,198 @@
+---
+description: "Instructions for setting up BNO055 9-DOF Absolute Orientation Sensor."
+title: "BNO055 9-DOF Absolute Orientation Sensor"
+params:
+  seo:
+    description: Instructions for setting up BNO055 9-DOF Absolute Orientation Sensor.
+---
+
+The `bno055` sensor platform allows you to use your BNO055 9-DOF Absolute Orientation Sensor
+([datasheet](https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bno055-ds000.pdf),
+[Adafruit](https://www.adafruit.com/product/2472)) with ESPHome.
+The [I2C Bus](/components/i2c) is required to be set up in your configuration for this sensor to work.
+
+The BNO055 is unique in that it features an onboard ARM Cortex-M0 processor that performs sensor fusion,
+combining data from the accelerometer, gyroscope, and magnetometer to provide absolute orientation outputs
+including Euler angles and quaternions. This removes the complexity of implementing sensor fusion algorithms
+on the microcontroller.
+
+```yaml
+# Minimal configuration entry
+sensor:
+  - platform: bno055
+    euler_heading:
+      name: "BNO055 Heading"
+    euler_roll:
+      name: "BNO055 Roll"
+    euler_pitch:
+      name: "BNO055 Pitch"
+```
+
+```yaml
+# Full configuration entry with all sensors
+sensor:
+  - platform: bno055
+    address: 0x29
+    update_interval: 1s
+    # Euler angles (absolute orientation)
+    euler_heading:
+      name: "BNO055 Heading"
+    euler_roll:
+      name: "BNO055 Roll"
+    euler_pitch:
+      name: "BNO055 Pitch"
+    # Quaternion (absolute orientation)
+    quaternion_w:
+      name: "BNO055 Quaternion W"
+    quaternion_x:
+      name: "BNO055 Quaternion X"
+    quaternion_y:
+      name: "BNO055 Quaternion Y"
+    quaternion_z:
+      name: "BNO055 Quaternion Z"
+    # Linear acceleration (without gravity)
+    linear_accel_x:
+      name: "BNO055 Linear Accel X"
+    linear_accel_y:
+      name: "BNO055 Linear Accel Y"
+    linear_accel_z:
+      name: "BNO055 Linear Accel Z"
+    # Gravity vector
+    gravity_x:
+      name: "BNO055 Gravity X"
+    gravity_y:
+      name: "BNO055 Gravity Y"
+    gravity_z:
+      name: "BNO055 Gravity Z"
+    # Raw accelerometer
+    accel_x:
+      name: "BNO055 Accel X"
+    accel_y:
+      name: "BNO055 Accel Y"
+    accel_z:
+      name: "BNO055 Accel Z"
+    # Gyroscope
+    gyro_x:
+      name: "BNO055 Gyro X"
+    gyro_y:
+      name: "BNO055 Gyro Y"
+    gyro_z:
+      name: "BNO055 Gyro Z"
+    # Magnetometer
+    mag_x:
+      name: "BNO055 Mag X"
+    mag_y:
+      name: "BNO055 Mag Y"
+    mag_z:
+      name: "BNO055 Mag Z"
+    # Temperature
+    temperature:
+      name: "BNO055 Temperature"
+```
+
+## Configuration variables
+
+### Euler Angles (Absolute Orientation)
+
+- **euler_heading** (*Optional*): Heading angle in degrees (0-360). All options from
+  [Sensor](/components/sensor).
+- **euler_roll** (*Optional*): Roll angle in degrees. All options from
+  [Sensor](/components/sensor).
+- **euler_pitch** (*Optional*): Pitch angle in degrees. All options from
+  [Sensor](/components/sensor).
+
+### Quaternion (Absolute Orientation)
+
+- **quaternion_w** (*Optional*): Quaternion W component. All options from
+  [Sensor](/components/sensor).
+- **quaternion_x** (*Optional*): Quaternion X component. All options from
+  [Sensor](/components/sensor).
+- **quaternion_y** (*Optional*): Quaternion Y component. All options from
+  [Sensor](/components/sensor).
+- **quaternion_z** (*Optional*): Quaternion Z component. All options from
+  [Sensor](/components/sensor).
+
+### Linear Acceleration (Gravity Removed)
+
+- **linear_accel_x** (*Optional*): Linear acceleration X-axis in m/s². All options from
+  [Sensor](/components/sensor).
+- **linear_accel_y** (*Optional*): Linear acceleration Y-axis in m/s². All options from
+  [Sensor](/components/sensor).
+- **linear_accel_z** (*Optional*): Linear acceleration Z-axis in m/s². All options from
+  [Sensor](/components/sensor).
+
+### Gravity Vector
+
+- **gravity_x** (*Optional*): Gravity vector X-axis in m/s². All options from
+  [Sensor](/components/sensor).
+- **gravity_y** (*Optional*): Gravity vector Y-axis in m/s². All options from
+  [Sensor](/components/sensor).
+- **gravity_z** (*Optional*): Gravity vector Z-axis in m/s². All options from
+  [Sensor](/components/sensor).
+
+### Raw Accelerometer
+
+- **accel_x** (*Optional*): Raw acceleration X-axis in m/s². All options from
+  [Sensor](/components/sensor).
+- **accel_y** (*Optional*): Raw acceleration Y-axis in m/s². All options from
+  [Sensor](/components/sensor).
+- **accel_z** (*Optional*): Raw acceleration Z-axis in m/s². All options from
+  [Sensor](/components/sensor).
+
+### Gyroscope
+
+- **gyro_x** (*Optional*): Angular velocity X-axis in degrees/s. All options from
+  [Sensor](/components/sensor).
+- **gyro_y** (*Optional*): Angular velocity Y-axis in degrees/s. All options from
+  [Sensor](/components/sensor).
+- **gyro_z** (*Optional*): Angular velocity Z-axis in degrees/s. All options from
+  [Sensor](/components/sensor).
+
+### Magnetometer
+
+- **mag_x** (*Optional*): Magnetic field X-axis in microtesla (µT). All options from
+  [Sensor](/components/sensor).
+- **mag_y** (*Optional*): Magnetic field Y-axis in microtesla (µT). All options from
+  [Sensor](/components/sensor).
+- **mag_z** (*Optional*): Magnetic field Z-axis in microtesla (µT). All options from
+  [Sensor](/components/sensor).
+
+### Other
+
+- **temperature** (*Optional*): Internal temperature of the sensor in Celsius. All options from
+  [Sensor](/components/sensor).
+- **address** (*Optional*, int): Manually specify the I2C address of the sensor.
+  Defaults to `0x29`. The alternative address is `0x28`.
+- **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval to check the sensor.
+  Defaults to `1s`.
+- **id** (*Optional*, [ID](/guides/configuration-types#id)): Manually specify the ID used for code generation.
+
+## ESP32 I2C Considerations
+
+The BNO055 uses I2C clock stretching, which can cause issues on some ESP32 variants. If you experience
+communication problems, try reducing the I2C frequency to 50kHz:
+
+```yaml
+i2c:
+  sda: GPIO21
+  scl: GPIO22
+  frequency: 50kHz
+```
+
+## Calibration
+
+The BNO055 performs automatic calibration during operation. For best results:
+
+1. **Gyroscope**: Keep the sensor still for a few seconds after power-on.
+1. **Magnetometer**: Move the sensor in a figure-8 pattern to calibrate.
+1. **Accelerometer**: Place the sensor in multiple orientations (e.g., all 6 faces of a cube).
+
+The sensor fusion algorithm (NDOF mode) requires all three sensors to be calibrated for optimal
+absolute orientation output.
+
+## See Also
+
+- [Sensor Filters](/components/sensor#sensor-filters)
+- {{< apiref "bno055/bno055.h" "bno055/bno055.h" >}}
+- [Adafruit BNO055 Guide](https://learn.adafruit.com/adafruit-bno055-absolute-orientation-sensor)
+- [BNO055 Datasheet](https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bno055-ds000.pdf)