Soracom

Users

スタートガイド

S+ Camera Basic が提供する API

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

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

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

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

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

curl -X GET http://127.0.0.1:8080/v1/cameraState
SSH で S+ Camera Basic にリモートアクセスする場合 の手順に従って、Napter でリモートアクセスしたときは、上記の方法を使います。

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

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

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

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

    詳しくは、S+ Camera Basic が提供する 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 Basic の状態を取得する 

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シャッタースピード

カメラの設定を変更する 

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

  • 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
    }'
    
ヘッダー 
ヘッダー説明
Content-Typeapplication/json
リクエストボディ 

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

プロパティ説明
width
height
カメラ画像の横幅および高さ (※)。
以下のいずれかの解像度 (横幅 x 高さ) を設定してください。なお、動画を録画する場合は、1280 x 720 に設定してください。
  • 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)

※解像度の違いについては、以下の画像を参考にしてください。

解像度

レスポンス 

カメラの状態および設定が 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 形式のファイルは、動画のプレイリストを配布するためのファイル形式です。取得した m3u8 形式のファイルを ffmpeg などで処理すると、動画データをダウンロードできます。

ffmpeg version 4.3.1 で動作を確認しています。
  • S+ Camera シリーズ 内部から API を呼び出す場合 (例:アルゴリズムから呼び出す場合、または SSH ログインした状態から呼び出す場合):

    呼び出せません。
  • 外部から API を呼び出す場合:

    curl -X GET ${surplusRemoteAccessURLforCameraSettings}/mosaic/v1/LocalHarvestAgent/m3u8/${startTime}/${endTime}/index.m3u8
    
パスパラメーター 
パラメーター説明
startTime (必須)動画の開始点の UNIX 時間 (秒)
endTime (必須)動画の終了点の UNIX 時間 (秒)
レスポンス 

パスパラメーターで指定した開始点 (startTime) と終了点 (endTime) に近い時刻の動画がリストアップされた m3u8 形式のファイルが返されます。

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