Skip to content
Snowbird Power Systems

Documentation

Getting started

From the anti-static bag to a sketch reading state of charge in about ten minutes.

What is in the bag

Every Snowbird board ships bare: the board, a pinout card and the compliance insert. No cell is supplied. You bring the battery, and the board makes it safe to build on.

The 1S boards (Snowbird Feather 1S, Snowbird Core 1S, Snowbird 18650, Snowbird Lite 1S) take a single lithium cell. The Snowbird Pack takes a 2S, 3S or 4S pack on an XT30 lead with a JST-XH balance connector. Which cell goes with which board is covered in Chemistries.

Plug in a cell

On a 1S board the battery connector is a 3-pin JST-PH: BAT, NTC, GND. A cell with a built-in thermistor plugs straight in. A two-wire cell works too, but check the wire order before plugging it in. Cheap pouch cells arrive with the red and black wires swapped more often than you would think. The board survives a reversed cell, but it will not run from one.

On the Snowbird 18650, drop the cell into the holder with the positive end at the marked contact. The NTC pad in the holder rests against the cell wrap.

On the Snowbird Pack, plug the XT30 first, then the balance lead. The board reads the cell count from the balance connector and checks it against the cell-count resistor before it closes the battery switch. A mismatch is reported as a fault and the switch stays open.

Nothing happens yet. The battery switch stays open until the board has read the thermistor and the cell voltage, which takes about 200 ms, and then the 3.3 V rail comes up.

Plug in USB-C

Any USB-C source works: a phone charger, a laptop port, a power bank. The board reads the CC lines and takes 0.5 A, 1.5 A or 3 A as the source allows. There is no USB Power Delivery negotiation, so the input is always 5 V.

The yellow LED turns on when the cell is charging. It goes out and the green LED turns on when charging completes. Both LEDs can be disabled with the LED jumper on the underside if the board is going into something that must stay dark.

LED Meaning
Yellow steady Charging
Yellow blinking Charging held, usually because the cell is outside its temperature window
Green steady Charge complete; the load is running from USB
Both off, USB present Charging disabled, either by the PRIMARY jumper position or a fault. Read faults()
Both off, no USB Running from the battery

The host runs from USB while the cell charges. The power path never makes the load wait for the battery.

Install the library

Arduino: open the Library Manager and search for Snowbird Power. Install it with its dependencies. PlatformIO: add snowbird-power to lib_deps.

MicroPython: the package is snowbird. Install it with mip from the REPL:

import mip
mip.install("snowbird")

Both libraries talk to the board over I2C at address 0x36. On a Feather host the bus is already wired through the SDA and SCL positions. On anything else, use the Qwiic connector.

The first sketch

Set the chemistry and the capacity once. They are stored on the board and survive host reflashes.

#include <Snowbird.h>

Snowbird pmic;

void setup() {
  Serial.begin(115200);
  Wire.begin();
  pmic.begin(Wire);

  pmic.setChemistry(Chem::LiPo);        // refused above the jumper's ceiling
  pmic.setCapacity_mAh(2000);
  int applied = pmic.setChargeCurrent_mA(1000);
  Serial.printf("charge current: %d mA\n", applied);
}

void loop() {
  Serial.printf("%d %%  %d mV  %d mA  %s\n",
    pmic.soc(), pmic.voltage_mV(), pmic.current_mA(),
    pmic.inputSource() == Input::USB ? "USB" : "battery");
  delay(2000);
}

The same program in MicroPython:

from machine import I2C, Pin
from snowbird import Snowbird, Chem
import time

pmic = Snowbird(I2C(0, sda=Pin(4), scl=Pin(5)))
pmic.set_chemistry(Chem.LIPO)
pmic.set_capacity_mah(2000)
print("charge current:", pmic.set_charge_current_ma(1000))

while True:
    print(pmic.soc(), pmic.voltage_mv(), pmic.current_ma(), pmic.input_source())
    time.sleep(2)

setChargeCurrent_mA() returns the value actually applied. If you ask for 1000 mA on a 500 mAh cell you get 500 mA back, because the 1 C ceiling wins. See Library for the clamping rules.

The state of charge reads correctly from the first boot on Li-ion and LiPo. LiFePO4 and LiSOCl2 cells depend on coulomb counting, so the gauge needs the capacity you set and one full cycle to settle.

Check the Bluetooth broadcast

On the Snowbird Feather 1S, Snowbird Core 1S, Snowbird 18650 and Snowbird Pack, the board is already advertising BTHome packets every 2 s. Open nRF Connect on a phone and you will see a device named Snowbird-xxxx with state of charge, voltage, temperature and charging state in the advertisement. Home Assistant finds it without any setup. See Bluetooth.

The Snowbird Lite 1S has no radio.

Where to go next

  • Pinout for every header position and the pads off the header.
  • Feather hosts before stacking a Feather on top.
  • Chemistries before plugging in anything other than a LiPo.
  • Solar to size a panel.
  • Safety for what the board does when something goes wrong.
  • The three reference builds for complete, wired examples.
Pinout