USBカメラ

概要

レシピ言語ではUSBカメラを制御するAPIを準備しています。本サンプルコードではこのUSBカメラのAPIについて説明します。

USBカメラ機能の特徴

USBカメラ機能の概要を以下に示します。

※ UVC対応のUSBカメラでもカメラ機器によって動作しない場合があります。
※ 動作確認済みのUSBカメラは「ハードウェアリファレンスの動作確認済みUSBカメラ」を参照ください。
※USB Type-AはUSBカメラ専用となり、他のUSB機器を動かすことは出来ません。

USBカメラ制御

システム概要

USBカメラのAPIとシステム動作のイメージ図を以下に示します。

カメラ

USBカメラ機能はアプリケーションにて画像データを直接扱わない作りとなっており、カメラタスク側のカメラバッファに保存されている画像データをモデムタスクが参照して、HTTPボディーとして直接クラウドに送信する作りとなっています。

[カメラバッファについて]

受信した動画はJPEG画像として内蔵メモリのカメラバッファに保存します。
カメラバッファに保存できる枚数は解像度により異なります。

解像度 保存可能枚数
QVGA 190枚
VGA 46枚
HD 14枚
FlulHD 6枚

カメラバッファは最大数を超えた場合には、古い画像から上書きします。

USBカメラはサンプリングレート(撮影したJPEG画像をカメラバッファに記録する周期)を設定せずに撮影開始した場合、カメラバッファへの記録する周期はカメラ撮影のフレームレートに従います。サンプリングレートを事前に設定して撮影開始した場合、指定された周期でカメラバッファに画像を記録します。
細かい周期で記録する必要がない場合や、極力長期間の画像を記録したい場合はサンプリングレートを設定することを推奨します。

カメラバッファの基本動作

カメラバッファに記録される画像は、記録上限に達すると古い画像を消去して上書きするリングバッファ方式です。
カメラバッファに記録する速度よりLTE送信速度の方が遅い場合は全ての画像データを送信することができません。
例えばドライブレコーダーのように一定期間内の画像データのまとまりを欠落なくLTE送信したい場合は、USBカメラの撮影を停止してから、後にLTE送信することで実現できます。

画像データをLTE送信する際には、カメラバッファ内の「最新の画像」「最古の画像」「n番目に古い画像」のようにどの画像データを送信するか任意に指定することができます。
画像送信に成功すると、その画像より古い画像データは全て削除されます。もしカメラバッファ内の全てのデータを送信したい場合は古い画像から順番に送信するようにしてください。
全ての画像データを送信したい場合は「最古の画像」を指定して送信を複数回実行することで実現可能です。


USBカメラの制御

USBカメラ機能は以下の制御が可能です。
・撮影開始要求(解像度、フレームレートを実行時に指定する)
・撮影停止要求
・サンプリングレート(撮影したJPEG画像をカメラバッファに記録する周期)の変更要求
・USB接続状態の監視用リスナー登録要求
・USB接続状態の監視用リスナー登録解除要求

※USBカメラの設定変更要求や撮影開始/停止要求は単一タスクからのみ利用可能
※サンプリングレートは撮影するフレームレートとは別に最大60秒周期まで指定可能 (例えば、30fpsでUSBカメラ撮影を行いながら、カメラバッファへの記録は0.5秒に1枚という指定も可能)


カメラ制御のAPI

API 説明
1 UVC_VideoStreamCtrl() 撮影開始や停止、解像度やフレームレートの設定をする
2 UVC_BufCtrlSmpRate() カメラバッファに記録する周期を設定するためのAPI
3 UVC_RegistUsbVideoStatusListener() USB接続状態の監視リスナー登録要求

UVC_VideoStreamCtrl()

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の場合は3007.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やシステムリセットの発生にて、カメラバッファの画像データは全て削除されます。


UVC_BufCtrlSmpRate()

カメラバッファに記録する周期を設定を行うAPIです。

UVC_BufCtrlSmpRate(uint32 smp_rate)
    smp_rate : カメラバッファに記録する周期設定
      (0=fpsに従うまたは160000[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);
}

UVC_RegistUsbVideoStatusListener()

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の接続状態を監視

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);
}

サンプルコードの解説

「0401_指定時刻にカメラ撮影を行い画像をサーバへ送る」

このサンプルコードでは指定した時間にカメラを起動して、取得した画像を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