#include <twl/spi.h>u32 PM_GetBatteryLevel( u16* levelBuf );
| levelBuf | バッテリパックの電池残量状況を書き込むバッファ |
PM_RESULT_SUCCESS ならば、コマンドの実行が成功したことを表します。
PM_RESULT_BUSY ならば、 SPI が他の処理に占有されており処理できなかったことを示します。
PM_RESULT_ERROR ならば、この関数が使用できないことを示します。これは、NITRO モードで動作中に呼ばれたことを示します。それ以外で返ることはありません。
コマンドが成功した場合、levelBufで示されるアドレスにバッテリーパックの電池残量を表す値が格納されます。この値は 0 (PM_BATTERY_LEVEL_MIN) から 5 (PM_BATTERY_LEVEL_MAX) の6段階で表され、値が小さいほど電池残量は少ないことを表します。
バッテリーパックの電池残量を調べます。
この関数はARM7に該当動作を行うコマンドをPXIで送り、それを受け取ったARM7側がPMICを操作することで実行されます。
返り値が PM_RESULT_SUCCESS ならばコマンドの実行が成功したことを示し、u16型ポインタlevelBuf の先に結果が格納されます。この値は 0 (PM_BATTERY_LEVEL_MIN) から 5 (PM_BATTERY_LEVEL_MAX)
の6段階で表され、値が小さいほど電池残量は少ないことを表します。
| levelBuf に格納される値 | 電池残量(おおよその目安) | TWLでのLED色 |
|---|---|---|
| 5 (PM_BATTERY_LEVEL_MAX) | 100% | ■青 (点灯) |
| 4 | 60% | |
| 3 | 30% | |
| 2 | 10% | ■赤 (点灯) |
| 1 | 1% | ■■赤 (点滅) |
| 0 (PM_BATTERY_LEVEL_MIN) | 0% |
LED の色や点灯/点滅状態をアプリケーション側で制御することは出来ません。
電池残量は目安であり、バッテリーパックの個体差や劣化状況などで誤差があります。例えば levelBuf に格納される値 が 2 のところは 10% となっていますが、10% になったらこの値になる、という意味ではありません。大きく幅をもったおおよその目安ととらえるに留めておいてください。実際には 20%かもしれませんし 5%かもしれません。 バッテリー残量を6段階に分けた、その TWL 個体でのみ通用する指標の一つです。従って、取得した段階からのバッテリー残時間の一般的な値を算出したりすることはできません。
内部では、バッテリー残量はおおよそ 1 秒に一度程度でしか変わりません。バックライト輝度を最低の状態から一気に最高まで上げるような行為でハードウェア的には離散的に電池残量が変化した場合でも、電池残量を調べて結果を返すマイコンが連続値となるように調整します。
ただしSD や NAND を使用せず終了処理を必要としない、電池残量を使い切るようなアプリケーション(カードアプリ) はその限りではなく、LOW コールバックを設定していても、その前の段階から強制シャットダウンとなるレベルまで一気に残量が減り、電源が落ちる可能性があります。
電池残量が値1 の状態を検知すると PM_SetBatteryLowCallback() で設定した、電池残量が少ないことを通知するためのコールバック関数が呼ばれます。 ただし、「内部での値取得について」で書いたように、カードアプリのような終了処理を必要としないアプリケーションでは、内部で離散的に値が変化して 値1 の状態を飛ばして値0 の状態となることもあり、そうした場合はコールバックは呼ばれません。
NANDアプリのようにシャットダウン処理を必要とするアプリケーションではマイコンが調整するため離散的に変化してコールバックを呼び損ねるようなことはありません。電池残量が値0 の状態を検知するとハードウェアはシャットダウン処理を行います。SDやNANDを使用しないアプリケーションの場合、シャットダウン処理は行われません。
PM_GetBatteryLevel() と類似の関数として PM_GetBattery() がありますが、PM_GetBattery() では電池残量を2段階でしか知ることが出来ません。NITROハードウェアでは電池残量を2段階でしか取得できなかったのでこのような構成になっています。
この関数は TWL のハードウェア上でTWLモードで動作しているときのみ動作します。TWL ハードウェア上でNITROモードで動作している場合や、NITRO ハードウェア上で動作している場合は使用することが出来ません。関数を呼ぶことは出来ますが、PM_RESULT_ERROR を返します。TWL モードで PM_RESULT_ERROR を返すことはありません。
SPI はPM以外にも様々な処理で使用されています。そのようなときに本関数を呼び出すと、ARM7
までコマンドを送り、そこで BUSY という判定が行われ、処理は行われずに ARM9
へ PM_RESULT_BUSY が通知されます。また他の PM 処理を行っている最中に本関数を呼び出すと、ARM9 側でそれを判断し PM_RESULT_BUSY を返します。(この場合は ARM7 への通知を行う前に判断します。)
従って、確実に本関数を成功させようとすれば、次のように成功するまでループするようにしてください。(引数が間違っているというようなミスは考慮していません。)
(例)
while( PM_GetBatteryLevel( ... ) != PM_RESULT_SUCCESS )
{
}
PM_GetBattery, PM_SetBatteryLowCallback
2009/06/03 PM_Init() についての記述を削除 (OS_Init() が必須となったため)
2008/11/11 電池残量の目安を調整
2008/08/23 PM_RESULT_BUSY について言及
2008/04/09 電池残量の目安を調整
2008/02/07 電池残量の目安を追加
2008/01/24 初版