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

# PiSugarってなに？

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

<img width="500" alt="image.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3822515/2b091c01-7b90-4c4e-809a-b5a6f3e12cff.png">

<span style="color:gray">Image From : https://www.pisugar.com</span>

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

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

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

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

https://github.com/PiSugar/PiSugar/wiki/PiSugar-3-Series

### 環境

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

# ラズパイに搭載

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

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

# 各部説明

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

長辺（ラズパイ各種端子側）には、２つのボタンとバッテリー残量インジケーター、充電用USB端子があります。
USB端子に近い側のボタンには、[後述する](#ボタンの動作設定custom-button-function)機能割り当てが可能です。
<img width="600" alt="2025-04-30_13h52_50.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3822515/24c2eaaa-19ef-4816-9eb2-af2f9da8f9ee.png">

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


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

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

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

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

```bash
bash pisugar-power-manager.sh -c release
```

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

```bash
sudo dpkg-reconfigure pisugar-server
```
### 初期設定

**PiSugarの種類の選択**
<img width="1155" alt="2025-03-30_18h47_15.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3822515/a99213eb-39a9-4b3f-a3f3-f4686f1417b2.png">
使用しているPiSugarを選択します。今回はPiSugar3なので一番上を選択した状態でエンター。

**管理用ページのユーザー名を設定**
<img width="1156" alt="2025-03-30_22h34_04.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3822515/64bdb563-984d-4506-94f7-169a3940d92d.png">
後述するPiSugarの管理用ページにログインする際のユーザー名の設定です。今回は初期設定のAdminで行きました。

**管理用ページのパスワードを設定**
<img width="1157" alt="2025-03-30_22h34_24.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3822515/fd103cd4-35e8-4623-84a1-af7454dd6e24.png">
後述するPiSugarの管理用ページにログインする際のパスワードの設定です。この設定を怠ると、誰でも好きなコマンドを実行できたりしてしまう可能性があるので「0000」とかはやめときましょう。（そこまで難しくする必要もないけど）

**設定完了画面**
<img width="1157" alt="2025-03-30_22h34_46.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3822515/928e1e2b-8fe7-4d5d-badc-d981be4ed6f1.png">
設定おわったよ～このURLから管理用ページに入れるよ～って言ってます。

## PiSugar管理用ページ

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

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

ページにアクセスすると、まずユーザー名とパスワードを求められます。[先ほど](#初期設定)設定したものを入力しましょう。
<img width="300" alt="image.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3822515/f1083bd0-0c2b-44fc-aca6-128e16ad166d.png">

ログインに成功すると、管理用ページが表示できます。
ここから、PiSugarの各種動作の設定や状態の確認ができます。
<img width="700" alt="image.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3822515/9fde239b-d3f4-41ad-93ce-2a570ac6e320.png">

たとえば、バッテリーの充電が開始されると「**Charging**」の文字が表示されます。
<img width="500" alt="image.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3822515/215022fc-65a1-49c7-a40a-dacbac8f59f6.png">

## 各種機能の設定

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

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

### 自動電源オン（Schedule Wake Up）
PuSguarに搭載されるRTCによって、設定した時間にラズパイを起動させることができます。

- Disabled
  自動電源オン機能を使用しない（明示的に電源をオンにしなければ、ラズパイの電源が入ることはない）
  単純にラズパイをバッテリー運用したいときに最適です。
- Enabled
  設定した時間にラズパイの電源を自動的にオンにする。
  Repeatボタンより、適応する曜日も設定できます。
  <img width="902" alt="image.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3822515/aef0cf6d-277e-4156-9308-772c221e5653.png">
- On Power Restore
  仮にラズパイが電源を喪失（PiSugarの充電が無くなる等）してシャットダウンしたあと、PiSugarに充電ケーブルが接続されたときに自動的にラズパイの電源をオンにする。
  UPSとしての使い方に最も合っているかもしれないですね。

### ボタンの動作設定（Custom Button Function）
PiSugarの２つあるボタンのうち、充電端子のType-Cに近い方のボタンの設定を行えます。

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

<img width="600" alt="20250331_023112.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3822515/bd004f37-11f7-4fdb-8ec3-75524acdc7cc.png">

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

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

ボタンの機能として設定できる「**Custom Shell**」は任意のコマンドを実行することが可能です。
例えば、Single Tapに以下のように設定しておくとボタンが押された瞬間シャットダウンをすることができます。
<img width="888" alt="2025-03-31_03h19_19.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3822515/630815c3-85db-4eb6-b852-ae364d067605.png">

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


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

<img width="569" alt="2025-03-31_02h55_21.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3822515/a9fc7223-2bd3-4b9e-99a2-2babc08a9679.png">

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



# Python ライブラリ

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

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

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


## インストール

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

## 使い方

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

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

pisugar.test_via_tcp(<YOUR HOST ADDR>)
```

### PiSugarの情報取得と設定

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

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

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

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

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

version = s.get_battery_level()

print(version)
```
```plaintext
# 出力
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で無効。 |


<details><summary>各メソッドの出力例</summary>

```plaintext
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
```

</details>



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

<img width="768" alt="image.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3822515/575d6bf9-e49d-4f7b-af2f-7db2997ac665.png">

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

<img width="696" alt="image.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3822515/0b6601db-6d4f-4541-b182-3bca4f72a36e.png">

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