Skip to content

Commit bfea69a

Browse files
marat-iskhakovmarat-iskhakov
authored
Merge pull request #1 from faceterteam/readme
Updated Readme
2 parents 0edeae1 + fe72132 commit bfea69a

File tree

1 file changed

+212
-3
lines changed

1 file changed

+212
-3
lines changed

Diff for: ‎README.md

+212-3
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,19 @@ This SDK is designed to integrate IP cameras with the Faceter cloud video survei
77
![Integration scheme](integration_scheme.png)
88

99
**Device App** is an application on the camera that implements the connection between the Faceter CloudCam SDK and the camera platform
10+
1011
**Platform SDK** is a camera manufacturer’s platform, it can be the original SDK from the chip manufacturer (SigmaStar, Ingenic, Goke, etc.), or the vendor’s middleware platform built on top of them
11-
**Faceter CloudCam SDK** – modules that implement interaction with the cloud and Faceter applications. The SDK requires a local RTSP stream, which is transmitted to the Faceter cloud using RTSP-push technology.
1212

13-
## Step-by-Step Guide:
13+
**Faceter CloudCam SDK** – modules that implement interaction with the cloud and Faceter applications. The SDK requires a local RTSP stream, which is transmitted to the Faceter cloud using RTSP-push technology
14+
15+
## Intergration sample
16+
17+
An example of code with stubs describing intergation process is shown in [integration_sample.c](integration_sample.c)
18+
19+
## Step-by-Step Guide
1420

1521
1. Initialize library with FaceterClientInit
16-
2. Implement registration in Faceter cloud trough QR code scanning and WS-Discovery
22+
2. Implement registration in Faceter cloud through QR code scanning and WS-Discovery
1723
3. Implement additional methods for controlling the camera via the cloud:
1824
turning the microphone on/off, rotating the image, ...
1925
4. Implement transmission of all detections supported by the camera
@@ -25,13 +31,216 @@ This SDK is designed to integrate IP cameras with the Faceter cloud video survei
2531

2632
### Initialization
2733

34+
First step of integration process is library initialization
35+
36+
```
37+
const char* settingsPath = "/etc/faceter-client-settings.json";
38+
const char* serialNumber = GetSerialNumber();
39+
40+
//library initialization
41+
if (FaceterClientInit(ControlHandler, settingsPath, serialNumber) < 0) {
42+
return 0;
43+
}
44+
```
45+
46+
FaceterClientInit accepts 3 parameters:
47+
48+
- **ControlFunction** - callback from library with control code and parameters
49+
- **settingsPath** - path to the settings file in json format that will be parsed and validated
50+
- **serialNumber** - unique device id, could be NULL (it will be generated from MAC address)
51+
52+
Returns 0 on success and -1 if some error value occurs
53+
54+
#### Settings file structure
55+
An example of settings file is [faceter-client-settings.json](faceter-client-settings.json)
56+
57+
* rtspMainUrl - url of the RTSP stream from local RTSP server with user and password
58+
> "rtspMainUrl": "rtsp://root:12345@127.0.0.1/stream=0"
59+
* rtspSubUrl - secondary stream url, could be empty
60+
> "rtspSubUrl": ""
61+
* cameraModel - camera model name, shown in application
62+
> "cameraModel": "Faceter"
63+
* firmwareSaveDir - writable location where firmware update will be downloaded
64+
> "firmwareSaveDir": "/tmp"
65+
* endroidPort - port for internal library http server (optional, default 7654)
66+
* discoveryPort - port for WS-Discovery (optional, default 3702)
67+
* certFilePath - path to the CA certificate file, becase library uses HTTPS requests
68+
> "certFilePath": "/etc/ssl/certs/ca-certificates.crt"
69+
* confFilePath - file where camera registration parameters will be stored (optional, default is dir where settings file located)
70+
> "/etc/faceter-camera.conf"
71+
* cameraConfig - describes video, audio and other settings. Can be used for setting up camera parameters
72+
* audio - audio config describes sample rate, codec, microphone and speaker activity
73+
* mainStream - video config describes frame rate, codec, bitrate and image size of main stream
74+
* subStream - same for substream
75+
* image - image rotation
76+
* detector - motion detector state
77+
* osd - OSD visibility
78+
* nightMode - enable or disable night mode
79+
* customConfig - here can be stored any other necessary settings in json format
80+
2881
### Registration
2982

83+
WiFi cameras require QR scanner. Also connection to WiFi network with ssid and password should be implemented. Registration process in this case consists of 3 steps:
84+
1. Library sends operation code **ControlCodeScanQr** with _not NULL_ parameter to start QR scanner
85+
86+
```
87+
case ControlCodeScanQr: {
88+
if (param != NULL) {
89+
//start QR code scanning
90+
QrScannerStart();
91+
} else {
92+
//stop QR code scanning
93+
QrScannerStop();
94+
}
95+
break;
96+
}
97+
```
98+
99+
2. Show QR code in Faceter application to the camera
100+
3. When QR code is scanned with QR scanner - call `FaceterClientOnQrScanned` with qr code value string
101+
102+
```
103+
void OnQrScannerScanSuccess(char* qrCode)
104+
{
105+
//pass scanned string to Faceter library
106+
FaceterClientOnQrScanned(qrCode);
107+
}
108+
```
109+
110+
4. If QR code is correct, code **ControlCodeScanQr** with _NULL_ parameter will be sent to stop QR scanner
111+
5. Library will sent **ControlCodeSetupWifi** with param _WifiConfig*_ to setup WiFi network
112+
113+
```
114+
...
115+
case ControlCodeSetupWifi: {
116+
//setup wifi with ssid and password
117+
WifiConfig* config = (WifiConfig*)param;
118+
WifiSetup(config->network, config->password);
119+
break;
120+
}
121+
...
122+
123+
/*
124+
* Implement wifi setup for wireless cameras
125+
*/
126+
void WifiSetup(const char* networkSsid, const char* password)
127+
{
128+
}
129+
```
130+
131+
6. If camera obtains internet access, registration will be finished. Otherwise process will be repeted from step 1
132+
30133
### Controlling camera
31134

135+
Faceter application can send commands to control camera paramets, such as microphone state (enabled or disabled).
136+
Library will send control code ControlCodeMicrophone
137+
```
138+
//control handler fragment
139+
...
140+
case ControlCodeMicrophone: {
141+
//control microphone
142+
if (param != NULL) {
143+
//enable microphone on camera
144+
} else {
145+
//disable microphone on camera
146+
}
147+
break;
148+
}
149+
```
150+
After operation completes application must call `FaceterClientSetControlStatus(controlCode, statusCode)`
151+
where statusCode is **StatusCodeOk** if operation succeed or other on fail.
152+
If operation not supported statusCode can be set to **StatusCodeNotSupported**.
153+
For example if camera not supports playing audio, it will return status without processing operation
154+
```
155+
case ControlCodePlayAudio: {
156+
//play audio PCM buffer
157+
BufferParam* audioBuffer = (BufferParam*)param;
158+
statusCode = StatusCodeNotSupported;
159+
break;
160+
}
161+
```
162+
32163
### Motion detection events
33164

165+
When Motion Detector on camera detects motions events, they should be passed to library with `FaceterClientOnMotion`
166+
167+
```
168+
/*
169+
* Callback from Motion Detector
170+
*/
171+
void OnMotionDetected()
172+
{
173+
//send motion detection event to library
174+
FaceterClientOnMotion();
175+
}
176+
```
177+
34178
### Service functions
35179

180+
Application must provide these service functions if they supported:
181+
+ **Jpeg snapshot** - library sometime needs camera preivew jpeg image. ControlHandler with code **ControlCodeGetSnapshot**
182+
will be called. In response application should call `FaceterClientOnSnapshot` with snapshot jpeg bytes array
183+
184+
```
185+
case ControlCodeGetSnapshot: {
186+
//get camera snapshot
187+
char* snapshotJpegImage = "";
188+
long int snapshotJpegSize = 100;
189+
FaceterClientOnSnapshot(snapshotJpegImage, snapshotJpegSize);
190+
break;
191+
}
192+
```
193+
194+
+ **Registration reset** - if camera has _RESET_ button it can be used to reset registration state to initial.
195+
When button _RESET_ pressed longer than 3 seconds, apllication should call `FaceterClientReset` and reboot camera.
196+
197+
```
198+
/*
199+
* Handler of reset button pressed more than 3 seconds
200+
*/
201+
void OnResetButtonPressed()
202+
{
203+
//reset registration
204+
FaceterClientReset();
205+
RebootSystem();
206+
}
207+
```
208+
209+
Also for resetting registration state library can call ControlFunction with **ControlCodeRestartCamera** and _not NULL_ param
210+
211+
```
212+
case ControlCodeRestartCamera: {
213+
if (param != NULL) {
214+
OnResetButtonPressed();
215+
} else {
216+
RebootSystem();
217+
}
218+
break;
219+
}
220+
```
221+
+ **Serial number** - unique serial number needed for camera identification.
222+
Application must provide serial number string that will be the same after camera restarted. If no serial number provided camera will use MAC address as serial number
223+
+ **LED indication** - if camera has LED indicators they can be used to inform USER about current camera streaming state.
224+
Current state will be updated with ControlFunction code **ControlCodeStreamStatus**. If camera has two LED with different colors they should be used as follows
225+
```
226+
case ControlCodeStreamStatus: {
227+
StreamStatus streamStatus = *(StreamStatus*)param;
228+
if (streamStatus == StreamStatusStarted) {
229+
//turn on constant green led
230+
} else if (streamStatus == StreamStatusInit) {
231+
//green led slowly blinking
232+
} else {
233+
//red led (or green led) rapidly blinking
234+
}
235+
break;
236+
}
237+
```
238+
Where **green** LED is main indication color (could be any supported color) and **red** is additional color (if present)
36239

240+
## Library dependencies
37241

242+
Faceter CloudCam SDK depends on external libraries
243+
* pthread
244+
* json-c
245+
* libCurl (with RTSP protocol enabled)
246+
* embedTLS

0 commit comments

Comments
 (0)