RTClock
名称
内蔵RTC(real time clock:リアルタイムクロック)利用ライブラリ
/icons/hr.icon
概要
内蔵RTC(リアルタイムクロック)利用ライブラリは、
STM32マイコンに標準搭載されているRTCを利用するためのライブラリです。
RTCは独立したタイマです。
カウンタ値を書き込んで、システムの現在日時を設定することができます。(*1)
RTC の主な機能 (*1)
プログラマブルプリスケーラ:分周比は最大 2^20
32 ビット プログラマブルカウンタで長時間の測定が可能
2 つの個別クロック:APB1 インタフェースのための
PCLK1
RTC クロック(PCLK1 の 1/4以下の周波数であることが必要)
RTC のクロックソースは、次の 3 つのいずれかです。
128 分周の HSE(高速外部) オシレータクロック
LSE(低速外部) オシレータクロック
LSI(40 kHz 低速内蔵 RC) オシレータクロック
2 つの個別のリセットタイプ:
APB1 インタフェースは、システムリセットによってリセットされます。
RTC コア(プリスケーラ、アラーム、カウンタ、および分周回路)は、バックアップドメインリセットによってのみリセットされます。
3 本のマスク可能な専用割り込みリクエストライン:
アラーム割込み。ソフトウェアでプログラミング可能なアラーム割り込みを生成します。
秒割込み。プログラミング可能な周期(最大 1 秒)で周期的な割り込み信号を生成します。
オーバーフロー割り込み。内部のプログラマブルカウンタがゼロにロールオーバーしたことを検出します。
ライブラリリファレンス
/icons/hr.icon
メンバー変数(プロパティ)
■ tm_t tmm
メンバー関数(メソッド)
コンストラクタ
■ RTClock()
■ RTClock(rtc_clk_src src )
■ RTClock(rtc_clk_src src, uint16 prescaler )
RTClockのインスタンスを生成、内蔵RTCの初期化を行います。
指定した引数のクロック・ソース、プリスケーラーはベースにてクロック周期1Hzを生成して利用します。
引数
src :RTCのクロック・ソース
rtc_clk_src列挙型定数を指定します。次の指定が可能です。
RTCSEL_DEFAULT :クロック・ソースの指定は行いません
RTCSEL_NONE :クロック・ソースの指定は行いません
RTCSEL_LSE :LSE(低速外部クリスタル)オシレータクロック(LSEは32768 Hzでなければなりません)
RTCSEL_LSI :LSI(40 kHz 低速内蔵 RC)オシレータクロック
RTCSEL_HSE :128 分周の HSE(高速外部) オシレータクロック
srcの指定が無いコンストラクタを使用した場合、RTCSEL_HSEの指定となります。
prescaler :プリスケーラー(分周値)
クロック・ソースの分周値を指定します。
prescaler/(クロック・ソース - 1) = 1Hz の式より、
prescaler = クロック・ソース - 1 を指定する必要があります。
prescalerの指定値が0または、指定しないコンストラクタを使用した場合、次の値の指定となります。
RTCSEL_DEFAULT :プリスケーラーの指定は行いません
RTCSEL_NONE :プリスケーラーの指定は行いません
RTCSEL_LSE :0x7FFF
RTCSEL_LSI :0x9C3F
RTCSEL_HSE :0xF423
■ void breakTime(time_t epoch_time, tm_t & tmm);
与えられたtime_tを時間要素に分解します。
これは、Cライブラリのlocaltime()関数のよりコンパクトなバージョンです。
変換対象のtime_t型の値は1970年からオフセットされていることに注意してください。
※(注意)breaktime()関数は、安定版 R20170323でサポートしていません。
引数
epoch_time :変換対象時間 (time_t型、1970年1月1日00:00:00からの経過時間)
tmm :変換した時間要素の格納先(tm_t型)
time_t型はlong型と同じです。時刻を1970年1月1日00:00:00からの経過時間(秒)で保持しています。
変数名のepochは、「Epochとは新たな時代の始まり」を意味します。定冠詞を付けた"The Epoch"は、UNIXの時刻カウントの開始基準である1970年1月1日00:00:00(UTC)を意味します。
tm_t型は、 RTClock.hにて定義しています。次のように時刻成分を分解した形式で保持しています。 code:tm_t.h
typedef struct tm_t {
uint8_t year; // years since 1970
uint8_t month; // month of a year - 1 to 12 uint8_t day; // day of a month - 1 to 31 uint8_t weekday; // day of a week (first day is Monday) - 0 to 6 uint8_t pm; // AM: 0, PM: 1
uint8_t hour; // hour of a day - 0 to 23 uint8_t minute; // minute of an hour - 0 to 59 uint8_t second; // second of a minute - 0 to 59 } tm_t;
戻り値
なし
利用例
code:breakTimeSample.ino
RTClock rtclock (RTCSEL_LSE);
char weekday[]7 = {"Mon", "Tue", "Wed", "Thu", "Fri", "Sat","Sun"}; char ampm[]2 = {"AM","PM"}; void setup() {
tm_t tm;
Serial.begin(115200);
delay(300);
rtclock.breakTime(rtclock.getTime(), tm);
Serial.print("Year:"); Serial.println(tm.year + 1970);
Serial.print("Month:"); Serial.println(tm.month);
Serial.print("day:"); Serial.println(tm.day);
Serial.print("weekday:"); Serial.println(weekdaytm.weekday); Serial.print("AM/PM:"); Serial.println(ampmtm.pm); Serial.print("hour:"); Serial.println(tm.hour);
Serial.print("minute:"); Serial.println(tm.minute);
Serial.print("second:"); Serial.println(tm.second);
}
void loop() { }
■ time_t makeTime(tm_t & tmm)
時間要素をtime_tに変換します。
変換したtime_t型の時刻はその年は1970年からオフセットされていることに注意してください。
引数
tmm :時間要素(tm_t型)
※tm_t型については、breakTime()の説明を参照して下さい。
※(注意) maketime()関数は、安定版 R20170323でサポートしていません。
■ void setTime(time_t time_stamp)
RTCの時刻設定を行います。
引数
time_stamp :設定時刻(time_t型)
※time_t型については、breakTime()の説明を参照して下さい。
■void setTime(tm_t & tmm)
RTCの時刻設定を行います。
引数
tmm :設定時刻(tm_t型)
※tm_t型については、breakTime()の説明を参照して下さい。
■ time_t getTime()
RTCから時刻を読みその値を返します。
戻り値
読み取った時刻(time_t型)
■ void getTime(tm_t & tmm )
RTCから時刻を読みその値を返します。
引数
tmm :読み取った時間要素の格納先(tm_t型)
■ void now(tm_t & tmm )
本関数はマクロ関数です。getTime()を呼び出しています。
RTCから時刻を読み、その値を返します。
引数
tmm :読み取った時間要素の格納先(tm_t型)
■ uint8_t year(void)
RTCから時刻を読み、西暦年()を返します。
■ uint8_t month(void)
RTCから時刻を読み、月(1~12)を返します。
■ uint8_t day(void)
RTCから時刻を読み、日(1~31)を返します。
■ uint8_t weekday(void)
RTCから時刻を読み、曜日(0~6:月~日)を返します。
■ uint8_t hour(void)
RTCから時刻を読み、時刻(0~23)を返します。
■ uint8_t minute(void)
RTCから時刻を読み、分(0~59)を返します。
■ uint8_t second(void)
RTCから時刻を読み、秒(0~59)を返します。
■ uint8_t isPM(void)
RTCから時刻を読み、時刻が午後あるかの判定値(false:AM、true:PM)を返します。
■ uint8_t year(time_t t)
指定した引数t(time_t型変数)の年要素(1970年からの経過年)を返します。
■ uint8_t month(time_t t)
指定した引数t(time_t型変数)の月要素(1~12)を返します。
■ uint8_t day(time_t t)
指定した引数t(time_t型変数)の日要素(1~31)を返します。
■ uint8_t weekday(time_t t)
指定した引数t(time_t型変数)の週要素(0~6:日~土)を返します。
■ uint8_t hour(time_t t)
指定した引数t(time_t型変数)の時要素(0~23)を返します。
■ uint8_t minute(time_t t)
指定した引数t(time_t型変数)の分要素(0~59)を返します。
■ uint8_t second(time_t t)
指定した引数t(time_t型変数)の秒要素(0~59)を返します。
■ uint8_t isPM(time_t t)
指定した引数t(time_t型変数)の時刻が午後あるかの判定値(false:AM、true:PM)を返します。
■ time_t TimeZone(time_t t, int TZ)
標準時刻t、タイムゾーンTZからローカル時刻を求め、その値を返します。
引数
t :標準時刻(time_t型)
TZ :タームゾーン(時間 0~)
戻り値
ローカル時刻
■ time_t TimeZone(time_t t, int HTZ, int MTZ)
標準時刻t、タイムゾーン時刻HTZ、分MTZからローカル時刻を求め、その値を返します。
引数
t :標準時刻(time_t型)
HTZ :タームゾーン時刻(時間 0~)
MTZ :タームゾーン分(時間 0~)
戻り値
ローカル時刻
※この関数は、R2017/10/31にて追加されました。
■ void createAlarm(voidFuncPtr function, time_t alarm_time_t)
RTCアラーム特殊割込み(EXTIラインによるRTCアラーム、ウェイクアップ)を登録します。
引数
function :割り込みで呼び出される関数
alarm_time_t :アラーム時刻(time_t型)
■ void createAlarm(voidFuncPtr function, tm_t & alarm_tm)
RTCアラーム特殊割込み(EXTIラインによるRTCアラーム、ウェイクアップ)を登録します。
引数
function :割り込みで呼び出される関数
alarm_time_t :アラーム時刻(tm_t型)
■ void removeAlarm()
RTCアラーム特殊割込み(EXTIラインによるRTCアラーム、ウェイクアップ)の登録を削除します。
■ void attachSecondsInterrupt(voidFuncPtr function)
秒割込み(1Hz周期)を登録します。
引数
function :割り込みで呼び出される関数
■ void detachSecondsInterrupt()
秒割込み(1Hz周期)の登録を削除します。
■ void attachAlarmInterrupt(voidFuncPtr function)
RTCアラームグローバル割込みを登録します。
本関数呼び出しの前にsetAlarmTime()にてアラーム時刻の設定が必要です。
引数
function :割り込みで呼び出される関数
■ void attachAlarmInterrupt(voidFuncPtr function, time_t alarm_time)
RTCアラームグローバル割込みを登録します。
引数
function :割り込みで呼び出される関数
alarm_time_t :アラーム時刻(time_t型)
■ void detachAlarmInterrupt()
RTCアラームグローバル割込みの登録を削除します。
■ void setAlarmTime (tm_t & tm_ptr)
アラーム時刻を設定します。
■ void setAlarmTime (time_t alarm_time)
アラーム時刻を設定します。
/icons/hr.icon
サンプルスケッチ
時刻を設定し、1秒間隔で現在時刻を表示します。
code:rtc_sample.ino
RTClock rtc(RTCSEL_LSE);
char *wday[] = {"Mon","Tue","Wed","Thr","Fri","Sat","Sun"};
// セットアップ
void setup() {
struct tm_t t;
Serial.begin(115200);
while (!Serial) delay(100);
t.month = 8; // 月 0-11 0から始まることに注意 t.weekday = 5; // 曜日 0-6 0:月曜 ~ 6:日曜 rtc.setTime(t); // 時刻の設定
}
void loop() {
struct tm_t st;
rtc.getTime(st); // 時刻取得
sprintf(str, "%04d/%02d/%02d %s %02d:%02d:%02d", st.year+1970, // 西暦年
st.month, // 月
st.day, // 日
st.hour, // 時
st.minute, // 分
st.second // 秒
);
Serial.println(str);
delay(1000);
}
/icons/hr.icon
低水準関数はRTCデバイスを直接操作する関数群です。RTClockクラスライブラリから利用されています。
データ型
■ rtc_dev rtc :RTCデバイス型
パブリックメンバー
rtc_reg_map *regs :レジスタマップ
voidFuncPtr handlers[] :ユーザーIRQレジスタ
■rtc_reg_map :RTCレジスタマップ型
パブリックメンバー
__IO uint32 CRH : RTC 制御レジスタ(上位)
__IO uint32 PRLH : RTC プリスケーラロードレジスタ(上位)
__IO uint32 CRL : RTC 制御レジスタ(下位)
__IO uint32 PRLL : RTC プリスケーラロードレジスタ(下位)
__IO uint32 DIVH : RTC プリスケーラ分周レジスタ(上位)
__IO uint32 DIVL : RTC プリスケーラ分周レジスタ(下位)
__IO uint32 CNTH : RTC カウンタレジスタ(上位)
__IO uint32 CNTL : RTC カウンタレジスタ(下位)
__IO uint32 ALRH : RTC アラームレジスタ(上位)
__IO uint32 ALRL : RTC アラームレジスタ(下位)
デバイス
■rtc *RTC
RTCレジスタマップベースポインタ
■RTC_BASE: ((struct rtc_reg_map*)0x40002800)
レジスタのビット定義
RTC 制御レジスタ(上位)
ビット番号
■ RTC_CRH_OWIE_BIT [2] 1ビット(rw) :オーバーフロー割り込みイネーブル
■ RTC_CRH_ALRIE_BIT [1] 1ビット(rw) :アラーム割り込みイネーブル
■ RTC_CRH_SECIE_BIT [0] 1ビット(rw) :秒割り込みイネーブル
ビットセット
■ RTC_CRH_OWIE BIT(RTC_CRH_OWIE_BIT)
■ RTC_CRH_ALRIE BIT(RTC_CRH_ALRIE_BIT)
■ RTC_CRH_SECIE BIT(RTC_CRH_SECIE_BIT)
RTC 制御レジスタ(下位)
ビット番号
■ RTC_CRL_RTOFF_BIT [5] 1ビット(r) :RTC 操作オフ
■ RTC_CRL_CNF_BIT [4] 1ビット(rw) :設定フラグ
■ RTC_CRL_RSF_BIT [3] 1ビット(rcw0) :レジスタ同期フラグ
■ RTC_CRL_OWF_BIT [2] 1ビット(rcw0) :オーバーフローフラグ
■ RTC_CRL_ALRF_BIT [1] 1ビット(rcw0) :アラームフラグ
■ RTC_CRL_SECF_BIT [0] 1ビット(rcw0) :秒フラグ
ビットセット
■ RTC_CRL_RTOFF BIT(RTC_CRL_RTOFF_BIT)
■ RTC_CRL_CNF BIT(RTC_CRL_CNF_BIT)
■ RTC_CRL_RSF BIT(RTC_CRL_RSF_BIT)
■ RTC_CRL_OWF BIT(RTC_CRL_OWF_BIT)
■ RTC_CRL_ALRF BIT(RTC_CRL_ALRF_BIT)
■ RTC_CRL_SECF BIT(RTC_CRL_SECF_BIT)
API関数
■ void rtc_init(rtc_clk_src src)
RTCインターフェイスを初期化し、レジスタマップとバックアップレジスタへのアクセスを有効にします。
引数
src :RTCのクロック・ソース
rtc_clk_src列挙型定数を指定します。次の指定が可能です。
RTCSEL_DEFAULT :クロック・ソースの指定は行いません
RTCSEL_NONE :クロック・ソースの指定は行いません
RTCSEL_LSE :LSE(低速外部クリスタル)オシレータクロック(LSEは32768 Hzでなければなりません)
RTCSEL_LSI :LSI(40 kHz 低速内蔵 RC)オシレータクロック
RTCSEL_HSE :128 分周の HSE(高速外部) オシレータクロック
■ void rtc_attach_interrupt(uint8 interrupt, voidFuncPtr handler)
RTC割り込みをアタッチします。
引数
interrupt :アタッチする割り込み番号(列挙型定数 rtc_interrupt_idを指定)
次の値が指定可能です。
RTC_SECONDS_INTERRUPT : 秒割込み(1Hz周期)
RTC_OVERFLOW_INTERRUPT :オーバーフロー割り込み(内部のプログラマブルカウンタがゼロにロールオーバー)
RTC_ALARM_GLOBAL_INTERRUPT :RTCアラームグローバル割込み
RTC_ALARM_SPECIFIC_INTERRUPT :RTCアラーム特殊割込み(EXTIラインによるRTCアラーム、ウェイクアップ)
handler :指定された割り込みに接続するハンドラ(関数)
■ void rtc_detach_interrupt(uint8 interrupt)
RTC割り込みをデタッチします。
引数
interrupt :デタッチする割り込み番号(列挙型定数 rtc_interrupt_idを指定)
次の値が指定可能です。
RTC_SECONDS_INTERRUPT : 秒割込み(1Hz周期)
RTC_OVERFLOW_INTERRUPT :オーバーフロー割り込み(内部のプログラマブルカウンタがゼロにロールオーバー)
RTC_ALARM_GLOBAL_INTERRUPT :RTCアラームグローバル割込み
RTC_ALARM_SPECIFIC_INTERRUPT :RTCアラーム特殊割込み(ウェイクアップ)
■ uint32 rtc_get_count()
RTCのカウンタの値(32ビット)を返します。
カウンタが低プリスケーラで動作している場合、この値は不正確になる可能性があります。
■ void rtc_set_count(uint32 value)
RTCのカウンタ値(時間/日付)を設定します。
■ uint32 rtc_get_divider()
RTCのプリスケーラの値を返します。
■ void rtc_set_prescaler_load(uint32 value)
RTCのプリスケーラの値を設定します。
■ void rtc_set_alarm(uint32 value)
RTCのアラーム値を設定します。
■ void rtc_wait_finished()
直前の書き込み操作が完了するまで必要に応じて待機します。
■ void rtc_clear_sync()
レジスタ同期フラグをクリアします。
このフラグは、PRL / DIVまたはCNTへの書き込み後にハードウェアによって設定されます。
■ void rtc_wait_sync()
RTCレジスタが同期しているかどうかを確認するには、必要に応じて待ちます。
■ void rtc_enter_config_mode()
設定モードに入ります。
■ void rtc_exit_config_mode()
設定モードを終了します。
■ void rtc_enable_irq(uint8 interrupt)
RTC割り込みを有効にします。
interrupt :デタッチする割り込み番号(列挙型定数 rtc_interrupt_idを指定)
次の値が指定可能です。
RTC_SECONDS_INTERRUPT : 秒割込み(1Hz周期)
RTC_OVERFLOW_INTERRUPT :オーバーフロー割り込み(内部のプログラマブルカウンタがゼロにロールオーバー)
RTC_ALARM_GLOBAL_INTERRUPT :RTCアラームグローバル割込み
RTC_ALARM_SPECIFIC_INTERRUPT :RTCアラーム特殊割込み(ウェイクアップ)
■ void rtc_disable_irq(uint8 interrupt)
RTC割り込みを無効にします。
interrupt :デタッチする割り込み番号(列挙型定数 rtc_interrupt_idを指定)
次の値が指定可能です。
RTC_SECONDS_INTERRUPT : 秒割込み(1Hz周期)
RTC_OVERFLOW_INTERRUPT :オーバーフロー割り込み(内部のプログラマブルカウンタがゼロにロールオーバー)
RTC_ALARM_GLOBAL_INTERRUPT :RTCアラームグローバル割込み
RTC_ALARM_SPECIFIC_INTERRUPT :RTCアラーム特殊割込み(ウェイクアップ)
■ void rtc_enable_alarm_event()
RTCアラームイベントを有効にします。
このイベントを有効にすると、WFE経由で深い睡眠(deep sleep)から目を覚ますことができます。
■ void rtc_disable_alarm_event()
RTCアラームイベントを無効にします。
■ int rtc_is_second()
秒フラグ(秒割り込み発生)の状態を調べる
■ int rtc_is_alarm()
アラームフラグ(アラーム割り込み発生)の状態を調べる
■ int rtc_is_overflow()
オーバーフローフラグ(オーバーフロー割り込み発生)の状態を調べる
脚注
このドキュメントは、たま吉がRTClockライブラリのソースを解析し執筆ししています。