ラズパイをバッテリー運用できるPiSugarの使い方

PiSugarってなに？

PiSugarとは、Raspberry Piをバッテリー駆動で使うことができるようになるRaspberry Piの拡張パーツです。

Image From : https://www.pisugar.com

Raspberry Piはときたま「ラズパイ」とも呼ばれる有名な高機能マイコンですが、基本的にUSB電源による常時給電が必要です。
つまり、スマホのように持ち運ぶ用途にはそのままでは活用できません。

しかし、PiSugarを使うとそれが可能になります。

部活関係のプロジェクトでこのPiSugarを使う機会があったのですが、いかんせん日本語での情報が少なく手探りで進めなければいけませんでした。
本記事では、このPiSugarのセットアップからPythonのAPIによる制御までを書いていきます。

基本的に公式GitHubのドキュメントを読みながら作業しました。

環境

• Raspberry Pi Zero 2 W
• Raspberry Pi OS Bookworm
• PiSugar3

ラズパイに搭載

まずはPiSugarをラズパイにくっつけなければいけません。
PiSugarがはじめから制御基板とバッテリーがセットになっていて、組み立ては至極簡単になっています。
PiSugarの基板面とラズパイの裏面をあわせるように重ねて、４隅を付属のネジで止めるだけです。
ただし、PiSugarのポゴピンとラズパイの裏面のピンが噛み合うようにしなければなりません。

このボゴピンを通して、PiSugarとラズパイが通信します。

各部説明

まず、PiSugarで一番目立つのがバッテリーでしょう。
このバッテリーは基盤と磁石でくっついているので、簡単に外すことができます。ただし、ケーブルははんだ付けされているので、断線してしまわないように注意が必要です。
基盤にはPiSugarのバージョンが印刷されてます。

長辺（ラズパイ各種端子側）には、２つのボタンとバッテリー残量インジケーター、充電用USB端子があります。
USB端子に近い側のボタンには、後述する機能割り当てが可能です。

また、USB端子から遠いほうのボタンは一回押しでバッテリー残量の確認、二回押し⇢長押し（・ーのイメージ）でラズパイの電源を入れることができます。

ソフトウェアのインストール

ラズパイでPiSugarを使用できるようにするためのソフトウェアをインストールしなければなりません。（公式Docにも書いてある）
まず、wgetを叩いてBashスクリプトファイルを取得。

wget https://cdn.pisugar.com/release/pisugar-power-manager.sh

ダウンロードが済んだら、以下コマンドでスクリプトを実行してインストールを実行。
追加必要なソフトウェア（依存パッケージ等）も自動でインストールされるので、多少時間がかかります。

bash pisugar-power-manager.sh -c release

インストールが完了すると、PiSugarの初期設定用インターフェイスが起動するはずです。
ここにも書かれているように、以下コマンドで再設定が可能なので焦らずゆっくり操作します。

sudo dpkg-reconfigure pisugar-server

初期設定

PiSugarの種類の選択

使用しているPiSugarを選択します。今回はPiSugar3なので一番上を選択した状態でエンター。

管理用ページのユーザー名を設定

後述するPiSugarの管理用ページにログインする際のユーザー名の設定です。今回は初期設定のAdminで行きました。

管理用ページのパスワードを設定

後述するPiSugarの管理用ページにログインする際のパスワードの設定です。この設定を怠ると、誰でも好きなコマンドを実行できたりしてしまう可能性があるので「0000」とかはやめときましょう。（そこまで難しくする必要もないけど）

設定完了画面

設定おわったよ～このURLから管理用ページに入れるよ～って言ってます。

PiSugar管理用ページ

PiSugarと同じネットワークに接続されている状態で、http://ラズパイのローカルIPアドレス:8421をブラウザで開くと、PiSugarの管理用ページに入ることができます。

eduroamやru-wifiなどの大学ネットワークにつながっている場合には、このページにアクセスできません。
スマホのテザリングにラズパイとパソコン両方を繋いだり、自宅のWi-Fiでやったり、大学のネットワーク以外でないといけません。

ページにアクセスすると、まずユーザー名とパスワードを求められます。先ほど設定したものを入力しましょう。

ログインに成功すると、管理用ページが表示できます。
ここから、PiSugarの各種動作の設定や状態の確認ができます。

たとえば、バッテリーの充電が開始されると「Charging」の文字が表示されます。

各種機能の設定

このページでは、以下のようなPiSugarの基本的な機能をGUIで設定することができます

• 自動電源オン
• ボタンの動作設定
• セーフシャットダウン

自動電源オン（Schedule Wake Up）

PuSguarに搭載されるRTCによって、設定した時間にラズパイを起動させることができます。

• Disabled
  自動電源オン機能を使用しない（明示的に電源をオンにしなければ、ラズパイの電源が入ることはない）
  単純にラズパイをバッテリー運用したいときに最適です。
• Enabled
  設定した時間にラズパイの電源を自動的にオンにする。
  Repeatボタンより、適応する曜日も設定できます。
  
• On Power Restore
  仮にラズパイが電源を喪失（PiSugarの充電が無くなる等）してシャットダウンしたあと、PiSugarに充電ケーブルが接続されたときに自動的にラズパイの電源をオンにする。
  UPSとしての使い方に最も合っているかもしれないですね。

ボタンの動作設定（Custom Button Function）

PiSugarの２つあるボタンのうち、充電端子のType-Cに近い方のボタンの設定を行えます。

Type-C端子から遠い方のボタンは、電源オンとインジケータ点灯用ボタンなのでカスタマイズはできません

一度押し（Single Tap）、二度押し（Double Tap）、長押し（Long Tap）の３つにそれぞれ割り当てることができます。

ただし、Single Tapにはシャットダウンを割り当てられないので注意。（以下ののCustom Shellを使えば可能）

ボタンの機能として設定できる「Custom Shell」は任意のコマンドを実行することが可能です。
例えば、Single Tapに以下のように設定しておくとボタンが押された瞬間シャットダウンをすることができます。

さらに、実行したいコマンドをまとめてシェルスクリプトとして記述し、以下のようにbashコマンドで実行するようにすれば、複数のコマンドを実行することも簡単です。

bash path/to/shell-script/file.sh

セーフシャットダウン（Safe Shutdown）

PiSugarのバッテリー残量が設定値以下になったとき、バッテリーが完全に喪失する前にシャットダウンをする機能。
例えば、以下の場合だと「10%以下になったら15秒後にシャットダウンする」という設定です。

こうすることで、ラズパイで動作させるプログラムでもバッテリー残量を監視しておき、シャットダウン前に行いたい処理をシャットダウンまでの猶予（画像では15秒）の間に済ませる、ということができそうです。

Python ライブラリ

PiSugarではPythonのライブラリも用意されています。
このライブラリでは、先ほどの管理用ページから設定できることに加えて、さらに詳細な設定や情報取得も可能です。

基本的に、PiSugarをくっつけたラズパイから制御するのが無難でしょう。

たぶん、同じネットワークに接続されていれば他のコンピュータから実行できそうだけど、未検証。

インストール

他の外部ライブラリ同様、pipコマンドでラズパイにインストールできます。

pip install pisugar

使い方

まずは、PiSugarライブラリをインポートしておきましょう。

import pisugar

接続テスト
test_via_tcpメソッドで、PiSugarとの接続をテストすることができます。引数には、ラズパイのローカルIPアドレスを渡しましょう。

import pisugar

pisugar.test_via_tcp(<YOUR HOST ADDR>)

PiSugarの情報取得と設定

管理用ページよりも詳細な情報取得や設定も可能です。

基本的に

1. connect_tcpメソッドで接続
2. PiSugarServerクラスに接続情報を渡して、インスタンス化
3. そのオブジェクトの各種メソッドを実行して情報取得・設定

という流れで実行していきます。

例えば、PiSugarのバッテリー残量を得たいときは

import pisugar

conn, event_conn = connect_tcp(<YOUR HOST ADDR>)
s = pisuga.PiSugarServer(conn, event_conn)

version = s.get_battery_level()

print(version)

# 出力
72.6

各種メソッド

PiSugarServerクラスをインスタンス化した後に使用できるメソッドを一覧表にまとめました。

メソッド名	説明	引数
register_single_tap_handler	シングルタップイベントが発生した際に呼び出されるコールバック関数を登録します。イベント接続が必要です。	callback: イベント発生時に実行される関数オブジェクト
register_double_tap_handler	ダブルタップイベントが発生した際に呼び出されるコールバック関数を登録します。イベント接続が必要です。	callback: イベント発生時に実行される関数オブジェクト
register_long_tap_handler	ロングタップイベントが発生した際に呼び出されるコールバック関数を登録します。イベント接続が必要です。	callback: イベント発生時に実行される関数オブジェクト
get_version	PiSugarサーバーのバージョンを取得します。	なし
get_model	PiSugarのモデル名を取得します。	なし
get_fireware_version	PiSugar 3のファームウェアバージョンを取得します。	なし
get_battery_level	バッテリー残量 (%) を取得します。	なし
get_battery_voltage	バッテリー電圧 (V) を取得します。	なし
get_battery_current	バッテリー電流 (A) を取得します。	なし
get_battery_led_amount	バッテリーLEDの数を取得します (PiSugar 2)。	なし
get_battery_power_plugged	電源が接続されているかどうかを取得します。	なし
get_battery_allow_charging	バッテリーの充電が許可されているかどうかを取得します。	なし
get_battery_charging_range	バッテリーの充電範囲（下限と上限の%）を取得します。カンマ区切りの文字列またはNoneを返します。	なし
get_battery_charging	バッテリーが現在充電中かどうかを取得します。	なし
get_battery_input_protect_enabled	バッテリー入力保護が有効かどうかを取得します。	なし
get_battery_output_enabled	バッテリー出力が有効かどうかを取得します。	なし
get_battery_full_charge_duration	バッテリーが満充電になった後も充電を続ける時間を取得します (秒)。設定されていない場合はNoneを返します。	なし
get_battery_safe_shutdown_level	安全なシャットダウンを実行するバッテリー残量の閾値 (%) を取得します。	なし
get_battery_safe_shutdown_delay	安全なシャットダウンを実行するまでの遅延時間 (秒) を取得します。	なし
get_battery_auto_power_on	電源復旧時に自動的に電源をオンにする設定が有効かどうかを取得します。 (PiSugar 2ではRTCが数秒ごとにPMUを起動)	なし
get_battery_input_protect	バッテリー入力保護が有効かどうかを取得します (get_battery_input_protect_enabled と同じ機能)。	なし
get_battery_soft_poweroff	ソフトパワーオフ機能が有効かどうかを取得します (PiSugar 3)。	なし
get_system_time	オペレーティングシステムの現在時刻を datetime オブジェクトとして取得します。	なし
get_rtc_time	RTC（リアルタイムクロック）の現在時刻を datetime オブジェクトとして取得します。	なし
get_rtc_alarm_time	RTCのアラーム時刻を datetime オブジェクトとして取得します (日付部分は無意味)。設定されていない場合はNoneを返します。	なし
get_rtc_alarm_enabled	RTCアラームが有効かどうかを取得します。	なし
get_rtc_adjust_ppm	RTCの周波数補正値 (ppm) を取得します (PiSugar 3)。	なし
get_rtc_alarm_repeat	RTCアラームの繰り返し設定を取得します (ビット0-6が日曜から土曜に対応)。	なし
get_tap_enable	指定されたタップ機能（'single', 'double', 'long'）が有効かどうかを取得します。	tap: 有効状態を確認するタップの種類 ('single', 'double', 'long' のいずれか)。デフォルトは 'single'。
get_tap_shell	指定されたタップイベント（'single', 'double', 'long'）に割り当てられているシェルスクリプトを取得します。	tap: シェルスクリプトを取得するタップの種類 ('single', 'double', 'long' のいずれか)。デフォルトは 'single'。
get_auth_username	HTTP認証のユーザー名を取得します。	なし
get_anti_mistouch	電源ボタンの誤操作防止機能が有効かどうかを取得します (PiSugar 3)。	なし
get_temperature	PiSugarの温度を取得します。	なし
set_battery_charging_range	バッテリーの充電範囲を設定します。	lower_bound: 充電を開始するバッテリー残量の下限 (%)。 upper_bound: 充電を停止するバッテリー残量の上限 (%)。 (0.0 <= lower_bound < upper_bound <= 100.0)
set_battery_input_protect	バッテリーの入力保護を有効または無効にします。	enable: Trueで有効、Falseで無効。
set_battery_output	バッテリーの出力を有効または無効にします。	enable: Trueで有効、Falseで無効。
set_battery_full_charge_duration	バッテリーが満充電になった後も充電を続ける時間を秒単位で設定します。	seconds: 満充電後の充電継続時間 (秒)。
set_battery_allow_charging	バッテリーの充電を許可または禁止します。	enable: Trueで許可、Falseで禁止。
set_battery_safe_shutdown_level	安全なシャットダウンを実行するバッテリー残量の閾値を設定します。	level: シャットダウンを実行するバッテリー残量 (%)。(0.0 から 60.0 の範囲であるべき)
set_battery_safe_shutdown_delay	安全なシャットダウンを実行するまでの遅延時間を秒単位で設定します。	delay: シャットダウンまでの遅延時間 (秒)。
set_battery_auto_power_on	電源復旧時に自動的に電源をオンにする設定を有効または無効にします。	enable: Trueで有効、Falseで無効。
set_battery_force_shutdown	バッテリー出力を無効にし、PiSugarをシャットダウンします。	なし
set_battery_soft_poweroff	ソフトパワーオフ機能を有効または無効にします (PiSugar 3)。	enable: Trueで有効、Falseで無効。
rtc_pi2rtc	OSの時刻をRTCに設定します。	なし
rtc_rtc2pi	RTCの時刻をOSに設定します。	なし
rtc_web	ネットワーク時刻を取得し、OSとRTCの時刻を更新します。	なし
rtc_alarm_set	RTCのアラーム時刻と繰り返し設定を行います。	time: アラーム時刻 (datetime オブジェクト、日付部分は無視される)。 weekday_repeat: 曜日の繰り返し設定 (ビット0-6が日曜から土曜)。
rtc_alarm_disable	RTCアラームを無効にします。	なし
rtc_adjust_ppm	RTCの周波数補正値 (ppm) を設定します (PiSugar 3)。	ppm: 周波数補正値 (-500.0 から 500.0 の範囲であるべき)。
set_tap_enable	指定されたタップ機能（'single', 'double', 'long'）を有効または無効にします。	tap: 設定するタップの種類 ('single', 'double', 'long' のいずれか)。 enable: Trueで有効、Falseで無効。
set_button_shell	指定されたタップイベント（'single', 'double', 'long'）に実行するシェルスクリプトを設定します。	tap: 設定するタップの種類 ('single', 'double', 'long' のいずれか)。 shell: 実行するシェルスクリプト文字列。
set_auth	HTTP認証のユーザー名とパスワードを設定します。	username: 設定するユーザー名。 password: 設定するパスワード。
set_anti_mistouch	電源ボタンの誤操作防止機能を有効または無効にします (PiSugar 3)。	enable: Trueで有効、Falseで無効。

各メソッドの出力例

get_version 2.0.0
get_model PiSugar 3
get_battery_level 91.451744
get_battery_voltage 3.9739661
get_battery_current 0.0
get_battery_led_amount 4
get_battery_power_plugged False
get_battery_allow_charging True
get_battery_charging_range None
get_battery_charging False
get_battery_input_protect_enabled False
get_battery_output_enabled True
get_battery_full_charge_duration None
get_battery_safe_shutdown_level 10.0
get_battery_safe_shutdown_delay 15
get_battery_auto_power_on False
get_battery_soft_poweroff False
get_battery_input_protect False
get_system_time 2025-03-31 18:52:20.052000+09:00
get_rtc_time 2020-01-23 05:25:46+09:00
get_rtc_alarm_time 2000-01-01 18:40:30+09:00
get_rtc_alarm_enabled False
get_rtc_adjust_ppm 0
get_rtc_alarm_repeat 127
get_tap_enable single False
get_tap_enable double False
get_tap_enable long True
get_tap_shell single 
get_tap_shell double 
get_tap_shell long w
get_temperature 34.0

トラブル

[ラズパイのIP]:8421にアクセスしても、このようにページを開くことができない。

原因：PiSugarサーバーの設定
sudo dpkg-reconfigure pisugar-server を実行して再設定を行った際に、この画面で「127.0.0.1」を選択してしまったのがダメでした。
こっちを選ぶと、同じローカルLAN内のコンピュータからもアクセスができなくなってしまうらしい。
「public access」をインターネットへの公開と解釈違いしてしまいました。

解決法：「listening address」の設定で「0.0.0.0」を選択する
sudo dpkg-reconfigure pisugar-server を実行して、「listening address」を変更しましょう。
これだけで、同じローカルLANに存在するコンピュータからならアクセスができるようになります。