This is an old revision of the document!
Table of Contents
SJCAM SJ8 Pro WiFi API
When the WiFi is on, the camera has the IP address 192.168.42.1 and you can connect to it on the SJCAM ESSID with the default password 12345678. The camera offers an API over the TCP protocol on port 7878; you can open a TCP 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.
JSON Messages
This is what a JSON message sent from the host (e.g. the Android smartphone) to the SJ8 Pro looks like:
{"param":"2022-04-25 10:29:59","msg_id":2,"type":"camera_clock","token":2}
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):
{"msg_id":257,"token":0}
the answer from the SJCAM is something like this:
{"rval":0,"msg_id":257,"param":1}
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
sleep 5000 t ipc rpc clnt exec2 '/tmp/SD0/autoexec.rc'
autoexec.rc
#!/bin/sh /tmp/SD0/api-set-options
api-set-options
#!/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
Web References
- HTTP API
- HTTP API (Thieye T5e) - Not longer available: local copy
- AmbaCommandHelper.java APK 1.5.java Java code decompiled from YI app?