View Source Soleil (soleil v0.1.1)

The official support library for the Soleil power management and sleep control board for Raspberry Pi.

This library provides functions for managing device power, scheduling sleep durations and wake times, as well as reading battery information. It is designed to abstract low-level hardware interactions, providing a clean and intuitive API for developers.

Summary

Types

battery_info()

Functions

battery_info()

Reads battery information from the hardware.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

configure_fuel_gauge(opts)

Updates the configuration of the BQ27427 battery fuel gauge chip.

init(opts)

Callback implementation for GenServer.init/1.

power_off()

Powers off the device.

sleep_for(duration, unit \\ :second)

Puts the device to sleep for a specified duration.

sleep_until(datetime)

Puts the device to sleep until a specified datetime.

start_link(opts \\ [])

Starts the Soleil GenServer process.

wakeup_reason()

Reports the reason that the board woke from sleep.

Types

battery_info()

@type battery_info() :: %{
  state_of_charge: float(),
  voltage: float(),
  current: float(),
  temperature: float()
}

Functions

battery_info()

@spec battery_info() :: {:ok, battery_info()} | {:error, any()}

Reads battery information from the hardware.

This function queries the battery for its state of charge, voltage, average current consumption, and temperature.

Examples

iex> {:ok, info} = Soleil.battery_info()
iex> Map.keys(info)
[:state_of_charge, :voltage, :current, :temperature]

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

configure_fuel_gauge(opts)

@spec configure_fuel_gauge(keyword()) :: :ok | {:error, any()}

Updates the configuration of the BQ27427 battery fuel gauge chip.

Accepts the same parameters as start_link/1.

Examples

iex> Soleil.configure_fuel_gauge(battery_capacity: 1000, battery_energy: 3700)
:ok

init(opts)

Callback implementation for GenServer.init/1.

power_off()

@spec power_off() :: :ok | {:error, any()}

Powers off the device.

On supported hardware, this will initiate a shutdown sequence. On host environments (e.g., during development), it simulates the power-off behavior.

Examples

iex> :ok = Soleil.power_off()

sleep_for(duration, unit \\ :second)

@spec sleep_for(non_neg_integer(), :day | :hour | :minute | System.time_unit()) ::
  :ok | {:error, any()}

Puts the device to sleep for a specified duration.

The device will enter a low-power state and wake up after the specified duration.

Parameters

duration - The duration to sleep.
unit - the unit of duration.

Examples

iex> Soleil.sleep_for(60) # Sleep for 1 minute
:ok

sleep_until(datetime)

@spec sleep_until(NaiveDateTime.t()) :: :ok | {:error, any()}

Puts the device to sleep until a specified datetime.

The device will enter a low-power state and wake up at the specified time.

Parameters

datetime - A UTC NaiveDateTime representing the target wake-up time.

Examples

iex> :ok = Soleil.sleep_until(~N[2024-11-17 08:30:00])

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts the Soleil GenServer process.

This function initializes the state and prepares the library for use.

Options

:i2c_bus - The I2C bus to use for hardware communication (default: "i2c-1").
:battery_capacity - The rated battery capacity in mAh (default: 2000).
:battery_energy - The rated battery power in mWh (default: 7400).

Examples

iex> {:ok, pid} = Soleil.start_link(battery_capacity: 1000, battery_energy: 3700)
iex> is_pid(pid)
true

wakeup_reason()

@spec wakeup_reason() :: :alarm | :manual

Reports the reason that the board woke from sleep.

Reasons for wakeup include:

:alarm: when the RTC alarm triggers wakeup, such as after sleep_for/2 or sleep_until/1
:manual: when the pushbutton or hall sensor triggers wakeup

Examples

iex> Soleil.wakeup_reason()
:manual