|
| 1 | +--- |
| 2 | +title: Adding the Battery |
| 3 | +description: >- |
| 4 | + Connect the rechargeable LiPo battery to your ESPHome Starter Kit and cut the |
| 5 | + cord on your builds. |
| 6 | +--- |
| 7 | +# Adding the Battery |
| 8 | + |
| 9 | +The battery cuts the cord on your starter kit. It's a rechargeable 3.7V 2800mAh LiPo that plugs into the ESP32-C6 with a 2-pin JST-PH 2.0 connector, so your builds can live anywhere in the home, not just next to a USB port. The ESP32-C6 charges it over the same USB-C cable you've been using all along. |
| 10 | + |
| 11 | +!!! note "Before you start" |
| 12 | + |
| 13 | + Work through the two prerequisites first: |
| 14 | + |
| 15 | + * [Start Here](/products/ESPHome-Starter-Kit/start-here.md) to unbox the kit and get familiar with the ESP32-C6. |
| 16 | + * [First Steps](/products/ESPHome-Starter-Kit/setup/first-steps.md) to install ESPHome Device Builder and create your starter kit device. |
| 17 | + |
| 18 | +## Attach the battery |
| 19 | + |
| 20 | +The battery connector only fits one way, but check the wire colors before you push it in. (1) |
| 21 | +{ .annotate } |
| 22 | + |
| 23 | +1. With the connector lined up, the black (ground) wire sits on the side closest to the ESP32-C6 chip and the red wire on the side closest to the USB-C port. If the wires are reversed, stop and don't force it. |
| 24 | + |
| 25 | +Push the connector into the battery port until it seats fully. |
| 26 | + |
| 27 | + |
| 28 | + |
| 29 | +## Deep Sleep |
| 30 | + |
| 31 | +Wi-Fi is hungry. Left running around the clock, the ESP32-C6 will work through the battery quickly. The fix is the <a href="https://esphome.io/components/deep_sleep/" target="_blank" rel="noreferrer nofollow noopener">Deep Sleep</a> component, which powers the device down between readings so it sips power instead of gulping it. |
| 32 | + |
| 33 | +Add this to your device's YAML in ESPHome Device Builder: |
| 34 | + |
| 35 | +```yaml |
| 36 | +deep_sleep: |
| 37 | + id: deep_sleep_1 |
| 38 | + run_duration: 30s |
| 39 | + sleep_duration: 10min |
| 40 | +``` |
| 41 | +
|
| 42 | +With this config the device wakes every 10 minutes, stays awake for 30 seconds to connect and report its readings, then goes back to sleep. Tune both numbers to your project: longer sleeps mean longer battery life, shorter sleeps mean fresher data. |
| 43 | +
|
| 44 | +A few things to know before you rely on it: |
| 45 | +
|
| 46 | +* Deep sleep fits sensor modules best. The [Temp & Humidity module](/products/ESPHome-Starter-Kit/modules/temperature-humidity-module.md) only needs a reading every few minutes, so it can sleep the rest of the time. |
| 47 | +* A timer isn't the only way to wake up. A GPIO pin can wake the device too, so a press on the [Button module](/products/ESPHome-Starter-Kit/modules/button-module.md) can pull the ESP32-C6 out of deep sleep. Our <a href="https://github.com/ApolloAutomation/BTN-1" target="_blank" rel="noreferrer nofollow noopener">BTN-1</a> is built around exactly this trick: it sleeps for months on a battery and wakes the instant you press a button. |
| 48 | +* While the device sleeps it drops off Wi-Fi, so it shows as unavailable in Home Assistant and the web server between wake-ups. That's normal. |
| 49 | +* If an OTA update won't take because the device keeps falling asleep, add the Prevent Sleep switch below, or plug in the USB-C cable and flash it over the wire. |
| 50 | +
|
| 51 | +??? example "How the BTN-1 wakes on button press" |
| 52 | +
|
| 53 | + This is the deep sleep block from the <a href="https://github.com/ApolloAutomation/BTN-1/blob/main/Integrations/ESPHome/Core.yaml" target="_blank" rel="noreferrer nofollow noopener">BTN-1 firmware</a>. The `esp32_ext1_wakeup` section tells the ESP32-C6 to wake when any of the button pins goes high: |
| 54 | + |
| 55 | + ```yaml |
| 56 | + deep_sleep: |
| 57 | + id: deep_sleep_1 |
| 58 | + sleep_duration: 24h |
| 59 | + run_duration: 90s |
| 60 | + esp32_ext1_wakeup: |
| 61 | + mode: ANY_HIGH |
| 62 | + pins: |
| 63 | + - number: GPIO2 |
| 64 | + allow_other_uses: true |
| 65 | + - number: GPIO4 |
| 66 | + allow_other_uses: true |
| 67 | + - number: GPIO5 |
| 68 | + allow_other_uses: true |
| 69 | + - number: GPIO6 |
| 70 | + allow_other_uses: true |
| 71 | + ``` |
| 72 | + |
| 73 | + One difference for the starter kit: the Button module's pin reads LOW when pressed (it uses a pull-up), the opposite of the BTN-1's buttons. So on the starter kit you'd wake on `mode: ALL_LOW` with GPIO6 as the only pin. |
| 74 | + |
| 75 | +#### Add a Prevent Sleep switch |
| 76 | + |
| 77 | +A sleeping device is a hard one to update. Every Apollo battery device ships with a **Prevent Sleep** switch for exactly this reason, and you can build the same thing into your starter kit config. It's a template switch that holds the device awake while it's on: |
| 78 | + |
| 79 | +```yaml |
| 80 | +switch: |
| 81 | + - platform: template |
| 82 | + name: "Prevent Sleep" |
| 83 | + id: prevent_sleep |
| 84 | + icon: mdi:sleep |
| 85 | + restore_mode: RESTORE_DEFAULT_ON |
| 86 | + optimistic: true |
| 87 | + entity_category: config |
| 88 | + on_turn_on: |
| 89 | + then: |
| 90 | + - lambda: |- |
| 91 | + id(deep_sleep_1).prevent_deep_sleep(); |
| 92 | + on_turn_off: |
| 93 | + then: |
| 94 | + - lambda: |- |
| 95 | + id(deep_sleep_1).allow_deep_sleep(); |
| 96 | +``` |
| 97 | + |
| 98 | +The `restore_mode: RESTORE_DEFAULT_ON` line means the device stays awake by default. Get everything working and updated first, then flip the switch off in Home Assistant or the web server when you're ready for the sleep cycle to start. Toggle it while the device is awake, a sleeping device can't hear the command until its next wake-up. |
| 99 | + |
| 100 | +Our battery devices also support a Home Assistant helper that holds every Apollo device awake at once for firmware updates. The same pattern works here, see the [Awake HA Helper guide](/products/general/battery-sensors/awake-ha-helper.md) for the walkthrough. |
| 101 | + |
| 102 | +## Charging |
| 103 | + |
| 104 | +Plug the USB-C cable into the ESP32-C6 and the battery charges while the device keeps running. There's nothing to configure and no charger to buy, any USB-C power source works. |
| 105 | + |
| 106 | +If you ever need to disconnect the battery, grip the connector body and pull it straight out. Pulling on the wires can rip them out of the connector. |
| 107 | + |
| 108 | +--8<-- "_snippets/community-help.md" |
0 commit comments