Soracom

Users

スタートガイド
Home スタートガイド IoT デバイス S+ Camera シリーズユーザーガイド リファレンス

S+ Camera シリーズが提供する API

S+ Camera シリーズの販売およびサポートの終了について
  • 2024 年 6 月 30 日に S+ Camera シリーズの販売およびサポートを終了します。
  • 2024 年 12 月 31 日に S+ Camera シリーズなどのエッジデバイスの統合管理サービス (SORACOM Mosaic) の提供を終了します。

S+ Camera シリーズ では Web サービス (以下、API) が動作しています。この API を呼び出すことで、カメラの設定を変更したりカメラ画像を確認したりできます。

S+ Camera シリーズ 上で動作するアルゴリズムから API を呼び出す場合と、Napter でリモートアクセスして API を呼び出す場合は、エンドポイントが異なります。

アルゴリズムなど S+ Camera シリーズ内部から API を呼び出す

S+ Camera シリーズ 上で動作するアルゴリズムからは、以下のように API を呼び出します。

カメラの状態を確認する例:

curl -X GET http://127.0.0.1:8080/v1/cameraState
S+ Camera シリーズが提供する API を呼び出せないときは

S+ Camera シリーズ が提供する API を呼び出したときに以下のメッセージが表示されたときは、SORACOM Device Interface が inactive になっている可能性があります。

$ curl -X GET http://127.0.0.1:8080/v1/cameraState
curl: (7) Failed to connect to 127.0.0.1 port 8080: Connection refused

SORACOM Device Interface の状態を確認するには、SSH で S+ Camera シリーズにリモートアクセス して、以下のコマンドを実行します。

$ sudo systemctl status soracom-deviceinterface.service
● soracom-deviceinterface.service - "SORACOM Device Interface"
   Loaded: loaded (/etc/systemd/system/soracom-deviceinterface.service; enabled; vendor preset: enabled)
   Active: inactive (dead) since Mon 2022-02-14 17:08:34 JST; 1s ago
    :

Active: のあとの表示で、状態を判定できます。

  • inactive (dead): 停止しています。
  • active (running): 正常に動作しています。

SORACOM Device Interface を再起動するには、S+ Camera シリーズ を再起動する か、以下のコマンドを実行します。

$ sudo systemctl stop soracom-deviceinterface.service
$ sudo systemctl start soracom-deviceinterface.service
SSH ログインした場合も上記の方法を使います

SSH で S+ Camera シリーズにリモートアクセスする場合 の手順に従って、Napter でリモートアクセスしたときは、上記の方法を使います。

Napter でリモートアクセスして S+ Camera シリーズ外部から API を呼び出す

Napter を利用して S+ Camera シリーズ へリモートアクセスして、API を呼び出すこともできます。

リモートアクセスを有効にする

  1. S+ Camera シリーズ へのリモートアクセスを有効にします。

    詳しくは、S+ Camera シリーズが提供する API を外部から利用するためにリモートアクセスする場合 を参照してください。

  2. 以下のコマンドを実行して、URL を変数に代入します。

    ${surplusRemoteAccessURL} には、リモートアクセスを有効にしたときに [HTTP(S)] に表示された URL を入力してください。

    $ surplusRemoteAccessURLforCameraSettings=${surplusRemoteAccessURL}
    

API を呼び出す

Napter を利用して S+ Camera シリーズ へリモートアクセスした場合は、以下のように API を呼び出します。

カメラの状態を確認する例:

curl -X GET ${surplusRemoteAccessURLforCameraSettings}/mosaic/v1/DeviceInterface/deviceState

利用できる API

S+ Camera シリーズの状態を取得する

S+ Camera シリーズ の状態を取得します。

  • S+ Camera シリーズ 内部から API を呼び出す場合 (例:アルゴリズムから呼び出す場合、または SSH ログインした状態から呼び出す場合):

    curl -X GET http://127.0.0.1:8080/v1/deviceState
    
  • 外部から API を呼び出す場合:

    curl -X GET ${surplusRemoteAccessURLforCameraSettings}/mosaic/v1/DeviceInterface/deviceState
    
レスポンス
プロパティ説明
DeviceIDデバイス ID
Serial_Numberシリアル番号
Hardware_Versionハードウェアバージョン
Endpointエンドポイント
IMEI通信モジュールの識別番号
IMSIネットワークオペレーターが各契約者を一意に識別するための識別子
SIM_SerialIoT SIM のシリアル番号
ICCIDIoT SIM (バーチャル SIM/Subscriber を含む) を識別するための識別子
mem_armメモリ合計容量 (バイト)
Memory_Freeフリーメモリ容量 (バイト)
Radio_Signal_Strength無線信号強度 (dBm)
Cell_IDCell ID
SMNCServing Mobile Network Code
SMCCServing Mobile Country Code
throttledRaspberry pi の CPU スロットル状態
measure_tempCPU 温度
measure_clock_armCPU 周波数
measure_volts_coreCPU 動作電圧 (Core)
measure_volts_sdram_cCPU 動作電圧 (SDRAM controller)
measure_volts_sdram_iCPU 動作電圧 (SDRAM I/O)
measure_volts_sdram_pCPU 動作電圧 (SDRAM physical)
デバイスの状態により含まれないプロパティがあります

アルゴリズムでは、必ずプロパティの存在確認を行ってからプロパティを取得・処理するように実装ください。

カメラの状態および設定を取得する

カメラの状態および設定を取得します。

  • S+ Camera シリーズ 内部から API を呼び出す場合 (例:アルゴリズムから呼び出す場合、または SSH ログインした状態から呼び出す場合):

    curl -X GET http://127.0.0.1:8080/v1/cameraState
    
  • 外部から API を呼び出す場合:

    curl -X GET ${surplusRemoteAccessURLforCameraSettings}/mosaic/v1/DeviceInterface/cameraState
    
レスポンス

カメラの状態および設定が JSON 形式で表示されます。主なプロパティは以下のとおりです。

プロパティ説明
capturingカメラ撮影ステータス
0: 無効
1: 有効。GET /mosaic/v1/DeviceInterface/startCameraCapture を実行してから、GET /mosaic/v1/DeviceInterface/stopCameraCapture を実行するまでの間は、1 が返ります。
recordingカメラ録画ステータス
0: 停止中
1: 録画中。GET /mosaic/v1/DeviceInterface/startCameraRecording を実行してから、GET /mosaic/v1/DeviceInterface/stopCameraRecording を実行するまでの間は、1 が返ります。
width
height
画像サイズ (横幅および高さ)
framerateフレームレート
sharpnessシャープネス
contrastコントラスト
brightness明るさ
saturation彩度
ISOISO 感度
shutter_speedシャッタースピード
capturingLastErrorカメラのエラー状況
設定なし: エラーなし
1: カメラが停止している
2: 同じ画像が繰り返し撮影されている
imageErrorRebootカメラのエラーを検知した場合 (capturingLastError が設定された場合) の、OS 自動再起動機能のステータス
0: 無効
1: 有効

カメラの異常を検知したときに OS を自動的に再起動する

S+ Camera シリーズ には、カメラが停止していたり、同じ画像が繰り返し撮影されていることを検知したときに OS を自動的に再起動する機能が用意されています。この機能の有効 / 無効を切り替えます。

  • S+ Camera シリーズ 内部から API を呼び出す場合 (例:アルゴリズムから呼び出す場合、または SSH ログインした状態から呼び出す場合):

    curl -X GET http://127.0.0.1:8080/v1/startImageErrorReboot
    

カメラの撮影を有効化する 前に呼び出してください。

設定を確認するには、カメラの状態および設定を取得するimageErrorReboot を参照してください。

カメラを再起動する

カメラを再起動します。

  • S+ Camera シリーズ 内部から API を呼び出す場合 (例:アルゴリズムから呼び出す場合、または SSH ログインした状態から呼び出す場合):

    curl -X GET http://127.0.0.1:9000/mosaic/v1/SystemInterface/reboot?mode=0
    

カメラの設定を変更する

カメラの設定を変更します。

  • S+ Camera シリーズ 内部から API を呼び出す場合 (例:アルゴリズムから呼び出す場合、または SSH ログインした状態から呼び出す場合):

    curl -X PATCH http://127.0.0.1:8080/v1/cameraState \
    -H "Content-Type: application/json" \
    -d '{
      "width":640,
      "height":480
    }'
    
  • 外部から API を呼び出す場合:

    curl -X PATCH ${surplusRemoteAccessURLforCameraSettings}/mosaic/v1/DeviceInterface/cameraState \
    -H "Content-Type: application/json" \
    -d '{
      "width":640,
      "height":480
    }'
    
フォーカス (ピント) をあわせてください

カメラの設定を変更したときは、フォーカス (ピント) も調整してください。S+ Camera シリーズ にはオートフォーカス機能がありません。詳しくは、S+ Camera シリーズのフォーカス (ピント) の調整方法 を参照してください。

画像サイズ (横幅および高さ) とフレームレートは、カメラの撮影を有効化する 前に変更してください。

ヘッダー
ヘッダー説明
Content-Typeapplication/json
リクエストボディ

JSON 形式でカメラの設定を指定します。

プロパティ説明
width
height

画像サイズ (横幅および高さ) (*1)。

以下のいずれかのサイズ (横幅 x 高さ) を設定してください。

  • 1640 x 1232
  • 1640 x 922
  • 1280 x 720
  • 640 x 480
framerateフレームレート。
動画を録画する場合は、25 に設定してください。
sharpnessシャープネス (-100100)
contrastコントラスト (-100100)
brightness明るさ (0100)
saturation彩度 (-100100)
ISOISO 感度 (0: auto、100800)
shutter_speedシャッタースピード (16000000)
  • (*1) 機種によって、画像サイズ (width、height) の設定の意味が異なります。以下を参照してください。
S+ Camera Basic の画像サイズ (横幅 x 高さ) の設定について

S+ Camera Basic では、画像サイズ (横幅 x 高さ) に設定したサイズで切り取られた画像が出力されます。以下の画像を参考にしてください。

画像の切り取りサイズ 画像の切り取りサイズ

S+ Camera Basic で撮影した動画を画像解析に利用する際は、以下の設定を推奨します。

  • できるだけ広い範囲を撮影し、かつ高いフレームレートで撮影するには、画像サイズ (横幅 x 高さ) を 1280 x 720 に設定してください。
  • フレームレートよりも、撮影範囲を優先する場合は、1640 x 1232 に設定してください。
  • 画像サイズを 1640 x 922 または 640 x 480 に設定すると、高いフレームレートで撮影できますが、アルゴリズムの処理性能がボトルネックになり、意図した品質の解析は期待できません。
S+ Camera Design の画像サイズ (横幅 x 高さ) の設定について

S+ Camera Design で画像サイズ (横幅 x 高さ) を設定すると、設定したサイズに縮小された画像が出力されます。

レスポンス

カメラの状態および設定が JSON 形式で表示されます。主なプロパティは以下のとおりです。

プロパティ説明
capturingカメラ撮影ステータス
0: 無効
1: 有効。カメラの撮影を有効化する API を呼び出してから、カメラの撮影を無効化する API を呼び出すまでの間は、1 が返ります。
recordingカメラ録画ステータス
0: 停止中
1: 録画中。GET /mosaic/v1/DeviceInterface/startCameraRecording を実行してから、GET /mosaic/v1/DeviceInterface/stopCameraRecording を実行するまでの間は、1 が返ります。
width
height
画像サイズ (横幅および高さ)
framerateフレームレート
sharpnessシャープネス
contrastコントラスト
brightness明るさ
saturation彩度
ISOISO 感度
shutter_speedシャッタースピード

カメラの撮影を有効化する

カメラの撮影を有効化します。

  • S+ Camera シリーズ 内部から API を呼び出す場合 (例:アルゴリズムから呼び出す場合、または SSH ログインした状態から呼び出す場合):

    curl -X GET http://127.0.0.1:8080/v1/startCameraCapture
    
  • 外部から API を呼び出す場合:

    curl -X GET ${surplusRemoteAccessURLforCameraSettings}/mosaic/v1/DeviceInterface/startCameraCapture
    

この API の実行後 2 秒以上経ってから、そのほかの API を利用してください。

カメラの撮影を無効化する

カメラの撮影を無効化します。

  • S+ Camera シリーズ 内部から API を呼び出す場合 (例:アルゴリズムから呼び出す場合、または SSH ログインした状態から呼び出す場合):

    curl -X GET http://127.0.0.1:8080/v1/stopCameraCapture
    
  • 外部から API を呼び出す場合:

    curl -X GET ${surplusRemoteAccessURLforCameraSettings}/mosaic/v1/DeviceInterface/stopCameraCapture
    

この API の実行後 3 秒以上経ってから、そのほかの API を利用してください。

カメラ画像 (静止画・非圧縮データ) を取得する

カメラで撮影した静止画の非圧縮データ (width x height x RGB) を取得します。

あらかじめ カメラの撮影を有効化 してください。

  • S+ Camera シリーズ 内部から API を呼び出す場合 (例:アルゴリズムから呼び出す場合、または SSH ログインした状態から呼び出す場合):

    curl -X GET http://127.0.0.1:8080/v1/cameraImage --output image.bin
    
  • 外部から API を呼び出す場合:

    curl -X GET ${surplusRemoteAccessURLforCameraSettings}/mosaic/v1/DeviceInterface/cameraImage --output image.bin
    
レスポンス

カメラで撮影した静止画の非圧縮データ (width x height x RGB) が返されます。

カメラ画像 (静止画・JPEG 形式データ) を取得する

カメラで撮影した静止画の JPEG 形式データを取得します。

あらかじめ カメラの撮影を有効化 してください。

  • S+ Camera シリーズ 内部から API を呼び出す場合 (例:アルゴリズムから呼び出す場合、または SSH ログインした状態から呼び出す場合):

    curl -X GET http://127.0.0.1:8080/v1/cameraJpegImage?quality=85 --output image.jpg
    
  • 外部から API を呼び出す場合:

    curl -X GET ${surplusRemoteAccessURLforCameraSettings}/mosaic/v1/DeviceInterface/cameraJpegImage?quality=85 --output image.jpg
    
クエリパラメーター
パラメーター説明
quality (任意)JPEG 圧縮率。1100 の値を指定します。デフォルトは、75 です。
レスポンス

カメラで撮影した静止画の JPEG 形式データが返されます。

カメラ画像 (静止画・WebP 形式データ) を取得する

カメラで撮影した静止画の WebP 形式データを取得します。

あらかじめ カメラの撮影を有効化 してください。

  • S+ Camera シリーズ 内部から API を呼び出す場合 (例:アルゴリズムから呼び出す場合、または SSH ログインした状態から呼び出す場合):

    curl -X GET http://127.0.0.1:8080/v1/cameraWebpImage?quality=85 --output image.webp
    
  • 外部から API を呼び出す場合:

    curl -X GET ${surplusRemoteAccessURLforCameraSettings}/mosaic/v1/DeviceInterface/cameraWebpImage?quality=85 --output image.webp
    
クエリパラメーター
パラメーター説明
quality (任意)WebP 圧縮率。0100 の値を指定します。デフォルトは、30 です。
レスポンス

カメラで撮影した静止画の WebP 形式データが返されます。

カメラ画像 (動画) の録画を開始する

カメラで録画を開始します。

あらかじめ カメラの撮影を有効化 してください。

  • S+ Camera シリーズ 内部から API を呼び出す場合 (例:アルゴリズムから呼び出す場合、または SSH ログインした状態から呼び出す場合):

    curl -X GET http://127.0.0.1:8080/v1/startCameraRecording
    
  • 外部から API を呼び出す場合:

    curl -X GET ${surplusRemoteAccessURLforCameraSettings}/mosaic/v1/DeviceInterface/startCameraRecording
    

カメラ画像 (動画) の録画を終了する

カメラで録画を終了します。

  • S+ Camera シリーズ 内部から API を呼び出す場合 (例:アルゴリズムから呼び出す場合、または SSH ログインした状態から呼び出す場合):

    curl -X GET http://127.0.0.1:8080/v1/stopCameraRecording
    
  • 外部から API を呼び出す場合:

    curl -X GET ${surplusRemoteAccessURLforCameraSettings}/mosaic/v1/DeviceInterface/stopCameraRecording
    

m3u8 ファイルを取得する

開始時刻と終了時刻を指定して、m3u8 形式のファイルを取得します。取得した m3u8 形式のファイルを ffmpeg などで処理すると、動画データをダウンロードできます。

m3u8 形式のファイルは、動画のプレイリストを配布するためのファイル形式です。

ffmpeg version 4.3.1 で動作を確認しています。

アルゴリズムの実行環境には ffmpeg がインストールされていないため、アルゴリズムでは ffmpeg は実行できません。

  • S+ Camera シリーズ 内部から API を呼び出す場合 (例:アルゴリズムから呼び出す場合、または SSH ログインした状態から呼び出す場合):

    curl -X GET http://127.0.0.1:8086/v1/m3u8/${startTime}/${endTime}/index.m3u8
    
  • 外部から API を呼び出す場合:

    curl -X GET ${surplusRemoteAccessURLforCameraSettings}/mosaic/v1/LocalHarvestAgent/m3u8/${startTime}/${endTime}/index.m3u8
    
パスパラメーター
パラメーター説明
startTime (必須)
  • S+ Camera シリーズ 内部から API を呼び出す場合:動画の長さ-10 (秒)。たとえば、40 秒前から現在までの動画を取得する場合は、30 を指定します。
  • 外部から API を呼び出す場合:動画の開始点の UNIX 時間 (秒)。
endTime (必須)
  • S+ Camera シリーズ 内部から API を呼び出す場合:0 (秒)。常に、0 を指定します。
  • 外部から API を呼び出す場合:動画の終了点の UNIX 時間 (秒)。
レスポンス

パスパラメーターで指定した時間 (目安) に撮影された動画がリストアップされた m3u8 形式のファイルが返されます。

m3u8 形式のファイルを利用して、動画データをダウンロードする方法について詳しくは、リモートアクセスを利用してカメラ画像 (動画) をダウンロードする を参照してください。