Differences

This shows you the differences between two versions of the page.

--- doc:appunti:hardware:sjcam-8pro-api [2022/04/29 17:45] – [Ambarella msg_id Codes] niccolo
+++ doc:appunti:hardware:sjcam-8pro-api [2022/05/02 11:22] (current) – removed niccolo
@@ Line 1: / Line 1: @@
-====== SJCAM SJ8 Pro WiFi API ======
-The camera offers an **API** over the **TCP protocol** on port **7878**. When the WiFi is on, you can open a open connection with it and exchange JSON messages to control the camera. This is the interface used by the official app.
-The protocol was at least partially **reversed engineered** (see the [[#web_references|web references]] below).
-===== JSON Messages =====
-This is what a **JSON message** sent from the host (e.g. the Android smartphone) to the SJ8 Pro looks like:
-<code>
-{"param":"2022-04-25 10:29:59","msg_id":2,"type":"camera_clock","token":2}
-</code>
-The most important item of the message is the **msg_id**, for each code there may be other parameters that must be instantiated, usually **type** and **param**. The **token** represents the current session and must be obtained first.
-The first message sent from the host is the **AMBA_START_SESSION** (msg_id 0 257):
-<code>
-{"msg_id":257,"token":0}
-</code>
-the answer from the SJCAM is something like this:
-<code>
-{"rval":0,"msg_id":257,"param":1}
-</code>
-The returned value **rval** should be **zero**, generally a negative number means some error occurred. The token is received into the **param** item, generally is an integer increasing by one on every new connection.
-==== Ambarella msg_id Codes ====
-The names of the Ambarella codes (the first column in the following table) were taken from various sources on the net (see [[#web_references]]). Some were named by me, because I did not find any documentation about them (the ones prefixed with ???).
-^ Ambarella Name       ^ Value  ^ Use  ^
-| AMBA_START_SESSION   |    257 | Get initial session token.  |
-| AMBA_STOP_SESSION    |    258 | Terminate the session.  |
-| AMBA_GET_SETTING     |      1 | Get the value of a a single camera setting.  |
-| AMBA_SET_SETTING     |      2 | Set the value of a camera setting. Settings are the ones returned by AMBA_GET_ALL_CURRENT_SETTINGS, plus some others, like camera_clock, camera_mode, save_low_resolution_clip, stream_out_type, ...  |
-| AMBA_GET_ALL_CURRENT_SETTINGS  |  3 | Get current camera settings. Notice: some settings appear more than once, but setting one will change all of them.  |
-| AMBA_GET_SPACE       |      5 | Get card space, total and free.  |
-| AMBA_NOTIFICATION    |      7 | Notification message. Generally this message is not an answer to a previous host message and it does not contain the ''rval'' item.  |
-| AMBA_GET_SINGLE_SETTING_OPTIONS  |  9 | Get the list of values accepted by a setting.  |
-| AMBA_GET_DEVICEINFO  |  11 | Get camera brand, model, firmware and API version, etc.  |
-| ??? AMBA_CAMERA_OFF  |  12 | Power off the camera. The message must contain the item ''param:cam_off''.  |
-| AMBA_GET_BATTERY_LEVEL  |  13 | Get power state and battery charge percent.  |
-| AMBA_BOSS_RESETVF    |  259 | Re-enable the shutter button after an AMBA_STOP_VF message. The message fails if the camera is displaying some settings screen. The code is referenced with different names in other sources: sendResetVF, sendForceResetVF.  |
-| AMBA_STOP_VF  |  260 | In the SJCAM SJ8 Pro this message disables the shutter button. May be it was intended to disable the viewfinder?  |
-| AMBA_RECORD_START  |  513 | Start recording (timelapse, burst, ...)  |
-| AMBA_RECORD_STOP  |  514 | Stop recording.  |
-| AMBA_GET_RECORD_TIME  |  515 | Get current recording length in seconds.  |
-| AMBA_TAKE_PHOTO  |  769 | Take a photo.  |
-| ??? AMBA_GET_CURRENT_MODE_SETTINGS  |  2053 | Get current mode (video, photo, etc.) settings. It returns a subset of the AMBA_GET_ALL_CURRENT_SETTINGS message.  |
-| ??? AMBA_SET_WIFI  |  2055 | Change the WiFi connecting parameters (effective after a reboot). The message must contain ''type:ESSID'' and ''param:SecretPassword''. The Android app requires password to be at least nine characters long.  |
-^ AMBA_GET_RECORD_TIME ^^^
-| Returned message |||
-| msg_id  |  515 |
-| rval    |  -14 | Camera is not recording  |
-|         |    0 | OK  |
-| param   |  120 | Record length in seconds, if exists.  |
-===== Executing API commands at bootstrap =====
-It is possible to automatically execute some API calls at camera bootstrap, without connecting any WiFi device to the camera itself.
-In this scenario the **RTOS** operating system on the camera uses the **telnet** command to talk to the **GNU/Linux** operating system running on the same camera, which handles the API requests (the camera actually runs two operating system simultaneusly: RTOS and Linux).
-I was able to **create a script** to select the Color Profile automatically at boot. Remember that, due a firmware bug, the color profile choiche is not preserved across reboots, and you have to disable the Gyro Stabilizer before selecting the Color Profile.
-Executing that script at camera startup is a rather convoluted process:
-  * At bootstrap, the RTOS executes the **autoexec.ash** Ambarella Script.
-  * Using the command **t ipc rpc clnt exec2** it is possible to execute a script into the **GNU/Linux** operating system.
-  * The GNU/Linux environment has the **busybox** software, so it is possible to use the **telnet** command to establish a TCP connection with the API server at **localhost:7878**.
-  * The required **JSON commands** are sent to the API server to disable Gyro Stabilizer, select the Color Profile and then re enable Gyro Stabilizer.
-**WARNING**: It seems that the API implementation is rather buggy. I experienced several problems ranging from **commands not aknowledged** if sent with bad timing (not waiting enough time from one command to the next), even to suddenly **reboot**!
-Here there are the three files that must be created on the root directory of the SD card:
-**autoexec.ash**
-<code>
-sleep 5000
-t ipc rpc clnt exec2 '/tmp/SD0/autoexec.rc'
-</code>
-**autoexec.rc**
-<code>
-#!/bin/sh
-/tmp/SD0/api-set-options
-</code>
-**api-set-options**
-<code>
-#!/bin/sh
-#
-# Send some commands to the TCP:7878 API.
-# Set the color profile to "SJCAM - Vivid" and enable Gyro Stabilizer.
-# We should get the token number from msg_id 257, but this script
-# is executed at boot, so the token should be always "1".
-T=1
-# A pause of 0.5 is required for each command to be completed.
-# By trial we discovered that a pause of 0.4 is not sufficient.
-S=0.52
-{
-  echo '{"msg_id": 257, "token": 0}'; sleep 1.5;
-  echo '{"msg_id": 2, "type": "Gyro Stabilizer", "param": "Off",           "token": '$T'}'; sleep $S;
-  echo '{"msg_id": 2, "type": "Color Profile",   "param": "Flat",          "token": '$T'}'; sleep $S;
-  echo '{"msg_id": 2, "type": "Color Profile",   "param": "SJCAM - Vivid", "token": '$T'}'; sleep $S;
-  echo '{"msg_id": 2, "type": "Gyro Stabilizer", "param": "On",            "token": '$T'}'; sleep $S;
-  sleep 1.0;
-} | telnet localhost 7878
-echo
-</code>
-===== Web References =====
-  * **HTTP API**
-    * **[[https://www.goprawn.com/forum/ambarella-cams/4867-http-api-thieye-t5e|HTTP API (Thieye T5e)]]** - Not longer available: **{{.:sjcam:4867-http-api-thieye-t5e.html|local copy}}**
-    * **{{.:sjcam:foream_wireless_remote_control_api.pdf|Foream Wireless Remote Control API}}**
-    * **{{.:sjcam:ambacommandhelper.java_apk_1.5.java.txt|AmbaCommandHelper.java APK 1.5.java}}** Java code decompiled from YI app?
-    * **[[https://github.com/vogloblinsky/elmo-qbic-4-cam-rig-manager/blob/master/API_Reverse_engineering.md|API Reverse engineering]]**