レシピ言語ではUSBカメラを制御するAPIを準備しています。本サンプルコードではこのUSBカメラのAPIについて説明します。
USBカメラ機能の概要を以下に示します。
※ UVC対応のUSBカメラでもカメラ機器によって動作しない場合があります。
※ 動作確認済みのUSBカメラは「ハードウェアリファレンスの動作確認済みUSBカメラ」を参照ください。
※USB Type-AはUSBカメラ専用となり、他のUSB機器を動かすことは出来ません。
USBカメラのAPIとシステム動作のイメージ図を以下に示します。
USBカメラ機能はアプリケーションにて画像データを直接扱わない作りとなっており、カメラタスク側のカメラバッファに保存されている画像データをモデムタスクが参照して、HTTPボディーとして直接クラウドに送信する作りとなっています。
受信した動画はJPEG画像として内蔵メモリのカメラバッファに保存します。
カメラバッファに保存できる枚数は解像度により異なります。
解像度 | 保存可能枚数 |
---|---|
QVGA | 190枚 |
VGA | 46枚 |
HD | 14枚 |
FlulHD | 6枚 |
カメラバッファは最大数を超えた場合には、古い画像から上書きします。
USBカメラはサンプリングレート(撮影したJPEG画像をカメラバッファに記録する周期)を設定せずに撮影開始した場合、カメラバッファへの記録する周期はカメラ撮影のフレームレートに従います。サンプリングレートを事前に設定して撮影開始した場合、指定された周期でカメラバッファに画像を記録します。
細かい周期で記録する必要がない場合や、極力長期間の画像を記録したい場合はサンプリングレートを設定することを推奨します。
カメラバッファに記録される画像は、記録上限に達すると古い画像を消去して上書きするリングバッファ方式です。
カメラバッファに記録する速度よりLTE送信速度の方が遅い場合は全ての画像データを送信することができません。
例えばドライブレコーダーのように一定期間内の画像データのまとまりを欠落なくLTE送信したい場合は、USBカメラの撮影を停止してから、後にLTE送信することで実現できます。
画像データをLTE送信する際には、カメラバッファ内の「最新の画像」「最古の画像」「n番目に古い画像」のようにどの画像データを送信するか任意に指定することができます。
画像送信に成功すると、その画像より古い画像データは全て削除されます。もしカメラバッファ内の全てのデータを送信したい場合は古い画像から順番に送信するようにしてください。
全ての画像データを送信したい場合は「最古の画像」を指定して送信を複数回実行することで実現可能です。
USBカメラ機能は以下の制御が可能です。
・撮影開始要求(解像度、フレームレートを実行時に指定する)
・撮影停止要求
・サンプリングレート(撮影したJPEG画像をカメラバッファに記録する周期)の変更要求
・USB接続状態の監視用リスナー登録要求
・USB接続状態の監視用リスナー登録解除要求
※USBカメラの設定変更要求や撮影開始/停止要求は単一タスクからのみ利用可能
※サンプリングレートは撮影するフレームレートとは別に最大60秒周期まで指定可能 (例えば、30fpsでUSBカメラ撮影を行いながら、カメラバッファへの記録は0.5秒に1枚という指定も可能)
API | 説明 | |
---|---|---|
1 | UVC_VideoStreamCtrl() | 撮影開始や停止、解像度やフレームレートの設定をする |
2 | UVC_BufCtrlSmpRate() | カメラバッファに記録する周期を設定するためのAPI |
3 | UVC_RegistUsbVideoStatusListener() | USB接続状態の監視リスナー登録要求 |
USBカメラを制御/設定を行うAPIです。
UVC_VideoStreamCtrl(uint8 start, uint8 format, uint16 h_size, uint16 v_size, uint16 fps)
start : USBカメラの撮影開始/停止設定 (0:停止, 1:開始)
format : USBカメラの画像形式設定 (UVC_STREAM_CODEC_MJPEG固定)
h_size : 水平方向の解像度設定 (ex:1280)
v_size : 垂直方向の解像度設定 (ex:720)
fps : カメラのfps設定 ([0.1fps]単位で利用可)
(例えば30.0fpsの場合は300、7.5fpsの場合は75を設定する)
USBカメラの撮影開始は以下のように実施します。
#incliude "uvcAPI.h"
~
func any_func() {
// カメラ撮影スタート(解像度:HD, フレームレート:30[fps])
UVC_VideoStreamCtrl(UVC_STREAM_CTRL_START, UVC_STREAM_CODEC_MJPEG, 1280, 720, 300);
return(0);
}
開始要求によりUSBカメラ機器との接続処理が行われます。カメラの起動時間後(5~10秒)後に最初の画像がUSBカメラから送らてきます。
USBカメラ機器からの応答が無い場合は、USBカメラとの接続保証の観点で、接続のリトライ処理を数十秒周期で繰り返します。リトライ処理を止めたい場合は後述の撮影停止要求を実施ください。
USBケーブルの接続状況を監視したい場合は、後述の「USB接続状態の監視リスナー登録API」を利用することで監視することが可能です。例えば「USBカメラが接続されておらずUSB接続に失敗したこと」や「その後のリトライ処理を開始したこと」などをイベントで取得することができます。
USBカメラの撮影停止は以下のように実施します。
#incliude "uvcAPI.h"
~
func any_func() {
// カメラ撮影ストップ
UVC_VideoStreamCtrl(UVC_STREAM_CTRL_STOP, 0, 0, 0, 0);
return(0);
}
撮影を停止しただけではカメラバッファの画像データは削除されず、保持された状況を継続します。次の撮影開始要求や端末電源OFFやシステムリセットの発生にて、カメラバッファの画像データは全て削除されます。
カメラバッファに記録する周期を設定を行うAPIです。
UVC_BufCtrlSmpRate(uint32 smp_rate)
smp_rate : カメラバッファに記録する周期設定
(0=fpsに従う、または1~60000[msec]で指定)
サンプリングレート(撮影したJPEG画像をカメラバッファに記録する周期)変更は以下のように撮影を開始する前に設定を行います。
#incliude "uvcAPI.h"
~
func any_func() {
// サンプリングレートを2秒に1枚の設定に変更
UVC_BufCtrlSmpRate(2000);
// カメラ撮影スタート(解像度:HD, フレームレート:30[fps])
UVC_VideoStreamCtrl(UVC_STREAM_CTRL_START, UVC_STREAM_CODEC_MJPEG, 1280, 720, 300);
return(0);
}
USB制御ステータス変化通知のリスナー登録を行うAPIです。
UVC_RegistUsbVideoStatusListener(uint8 event_id, uint8 mode_sw)
event_id : イベント通知ID (1-254)
mode_sw: 登録設定 (0:登録解除, 1:登録設定)
USBバスの状態監視リスナー登録APIに対応 (例えば、USBカメラ抜去やストリーム開始や失敗といった状態変化をイベント通知で取得可能)
USBバスの状態監視リスナー登録APIは複数タスクから利用可能
※通知されるイベントは4章にて後述します。
カメラバッファから画像をクラウドに送信をする場合は、HTTP送信のAPIにて該当の画像を指定する形で送信を実施します。
MMG_SendHTTP()に対して、以下の引数を渡します。
第5引数:MMG_MOVIE_BUF_IDを代入
第6引数:カメラバッファの画像の選択方式
0x0000:最新の画像
0xFFFF:最古の画像、
それ以外の数値:nを指定した場合は最新の画像からn番手前に保存されている画像
※n=1の場合は、最新の画像のひとつ前の画像になります。
#incliude "modemMgrTask.h"
#incliude "uvcAPI.h"
~
※ 事前にHTTPに関する基本設定を済ませておく(ここでは詳細割愛します) ※
~
func any_func() {
// カメラバッファ内の最新の画像を送信する(第5引数と第6引数で画像指定を行う)
MMG_SendHTTP(
timeout,
sync,
ex_result,
send_id,
MMG_MOVIE_BUF_ID, // カメラバッファを意味する設定値
0, // 今回は「最新の画像」を設定
burst,
session,
retain,
http_rsp_code,
rcv_buff_id,
send_success_num
);
return(0);
}
USBとの接続状態の監視をするには、APIのUVC_RegistUsbVideoStatusListener()を利用することで、下記のような状態を知ることができます。
define名 | 数値 | 通知される契機 |
---|---|---|
UVC_RESULT_STOP | 1 | 撮影停止制御完了 |
UVC_RESULT_START | 2 | 撮影開始制御後最初の画像を取得 |
UVC_RESULT_NO_STREAM_TIMEOUT | 3 | タイムアウトによる撮影失敗 |
UVC_RESULT_STARTED_RETRY | 4 | 撮影のリトライ処理開始 |
UVC_RESULT_P0_VBUS_ON | 100 | カメラ以外の情報 |
UVC_RESULT_P1_VBUS_ON | 101 | カメラの電源供給開始 |
UVC_RESULT_P2_VBUS_ON | 102 | カメラ以外の情報 |
UVC_RESULT_P0_ENUMERATION_COMPLETED | 103 | カメラ以外の情報 |
UVC_RESULT_P1_ENUMERATION_COMPLETED | 104 | カメラのUSB接続完了 |
UVC_RESULT_P2_ENUMERATION_COMPLETED | 105 | カメラ以外の情報 |
UVC_RESULT_P0_VBUS_OFF | 106 | カメラ以外の情報 |
UVC_RESULT_P1_VBUS_OFF | 107 | カメラの電源供給停止 |
UVC_RESULT_P2_VBUS_OFF | 108 | カメラ以外の情報 |
UVC_RESULT_P1_DISCONNECT_HUB | 109 | カメラ抜去を検出 |
UVC_RESULT_P2_DISCONNECT_HUB | 110 | カメラ以外の情報 |
UVC_RESULT_P0_DISCONNECT_H7 | 111 | カメラ以外の情報 |
UVC_RESULT_CALLER_DIFFERENCE | 200 | 撮影中の別タスクからのAPI実行 |
UVC_RESULT_EXCLUSIVE | 201 | 同一タスクからのAPI重複実行 |
UVC_RESULT_BUFF_SETUP_ERROR | 202 | カメラバッファの初期化に失敗 |
UVC_RESULT_NOT_APPLICABLE_SMP_RATE | 203 | カメラバッファのサンプリングレートの範囲外指定 |
UVC_RESULT_NOT_APPLICABLE_RESOLUTION | 204 | 撮影開始要求時の解像度の不適切な指定 |
UVC_RESULT_NOT_APPLICABLE_FORMAT | 205 | 撮影開始要求時の画像圧縮形式の不適切な指定 |
UVC_RESULT_NOT_APPLICABLE_FPS | 206 | 撮影開始要求時のフレームレートの不適切な指定 |
UVC_RESULT_ERROR | 255 | その他エラー |
※"uvcAPI.h"に定義
USB接続の状態変化時のイベントが発行されます。
そのイベントの1つ目の引数(rcplib_TASK_GetArg(0))から、イベント発行理由を取得できます。
#incliude "uvcAPI.h"
~
//////////////////////////////////////////////////////////////////
// internal define //
//////////////////////////////////////////////////////////////////
// 内部非同期イベント
#define UNSYNC_EVENT_INIT 0
#define UNSYNC_EVENT_USB_BUS 1
~
// mainループ処理
void main_loop() {
~
// USBバスの状態変化時のイベント処理 (リスナー登録完了後、イベント通知が入るようになる)
else if(event_id == UNSYNC_EVENT_USB_BUS) {
event_usb_video_status_change(rcplib_TASK_GetArg(0));
}
~
}
~
func any_func() {
// USBバスの状態監視リスナー登録APIを登録のために実行
UVC_RegistUsbVideoStatusListener(UNSYNC_EVENT_USB_BUS, UVC_LISTENER_REGIST_ADD);
// 以降、指定したevent_id(UNSYNC_EVENT_USB_BUS)に対してUSBバス関連のイベントが通知されるようになる
return(0);
}
// USBバスの状態変化時のイベント処理
func event_usb_video_status_change(uint8 result) {
// ★USBバスの状態変化時時の処理をここに記載すること★
// resultからはイベントの詳細情報が得られる
return(0);
}
#incliude "uvcAPI.h"
~
func any_func() {
// USBバスの状態監視リスナー登録APIを登録解除のために実行
UVC_RegistUsbVideoStatusListener(event_id, UVC_LISTENER_REGIST_REMOVE);
// 以降、USBバス関連のイベントが通知されなくなる
return(0);
}
このサンプルコードでは指定した時間にカメラを起動して、取得した画像を1枚クラウドに送信します。指定する時間はサンプルコードの冒頭のデファイン値を変更します。
// <時刻アラーム関連>
// アラーム時間設定(日本標準時の15:30:00のアラーム設定値)
#define ALARM_HOUR 15
#define ALARM_MINUTES 30
#define ALARM_SECOND 0
#define ALARM_TIME (ALARM_HOUR*3600+ALARM_MINUTES*60+ALARM_SECOND+54000)%86400
送信先のホスト名、ポートを送りたいサーバに合わせてください。
// 通信先設定値
#define CONN_HOSTNAME "xxxxxx.xxxxxx.xx" // 接続先ホスト名
#define CONN_PORT 80 // 接続先ポート番号
各サンプルコードについて動作確認を行っておりますが、全ての環境において動作を保証するものではありません。正しく動作することを確認の上でご利用ください。
対応機種:KC4-C-100A/KC4-C-101A