Align BMA456H driver with Powerpod and document sensor integration.

Clarify hearable variant usage, clean up I2C/GPIO/tap init, and add README
coverage for hardware, boot behavior, deadzone paths, and logging.

Co-authored-by: Cursor <cursoragent@cursor.com>

main/bosch456.h

@@ -1,17 +1,30 @@
 #ifndef BOSCH456_H
 #define BOSCH456_H
 
+/**
+ * Powerpod driver for Bosch BMA456H (hearable variant) on the shared I2C bus.
+ *
+ * Vendor API: components/bma456 (bma4.c + bma456h.c only).
+ * Implementation: bosch456.c
+ */
+
 #include "driver/i2c_types.h"
 #include "esp_err.h"
 
-#define TOUCH_1 9
-#define TOUCH_2 8
+/** 7-bit I2C address (SDO low). */
+#define BMA456_I2C_ADDR 0x18
 
-#define BMA456_ADDRESS 0x18
+/** Sensor interrupt line → ESP32 GPIO (active high, rising edge). */
+#define BMA456_INT_GPIO 10
 
+/** Software filter: log accel only when |axis - last| > deadzone (raw LSB). */
 #define BMA456_DEFAULT_ACCEL_DEADZONE 100u
 
-/** Initialize BMA456 on the shared I2C bus. Returns ESP_OK or logs and skips sensor use. */
+/**
+ * Probe and configure the sensor on bus_handle (100 kHz device).
+ * On failure the device is removed and ESP_ERR_NOT_FOUND / ESP_FAIL is returned;
+ * firmware continues without a sensor (see bma456_is_ready()).
+ */
 esp_err_t init_bma456(i2c_master_bus_handle_t bus_handle);
 
 bool bma456_is_ready(void);
@@ -19,7 +32,7 @@ bool bma456_is_ready(void);
 void bma456_set_accel_deadzone(uint32_t deadzone_lsb);
 uint32_t bma456_get_accel_deadzone(void);
 
-/** Log accel sample only when any axis changed more than deadzone since last report. */
+/** Log accel when any axis moved more than deadzone since last reported sample. */
 void bma456_report_accel_if_changed(int16_t x, int16_t y, int16_t z);
 
 #endif