Version | Date | Description |
---|---|---|
V1.0.00 | 2008/04/02 |
|
V1.0.01 | 2008/06/12 |
|
V1.0.02 | 2008/07/18 |
|
V1.0.03 | 2008/11/11 |
|
V1.0.04 | 2008/12/05 |
|
V1.0.05 | 2008/12/19 |
|
V1.0.06 | 2008/12/29 |
|
V1.0.07 | 2009/10/07 |
|
V1.0.08 | 2010/08/11 |
|
V1.1.00 | 2010/10/20 |
|
V1.1.01 | 2011/5/23 |
|
V1.1.02 | 2012/2/10 |
|
V1.1.03 | 2012/9/18 |
|
The control session protocol provides the message handshaking protocol between decoders and encoders to exchange the control data and AudioOut data. In here, we defined the message format for Token (Authentication), Control Data Frames and AudioOut frames. Refer the connection management for further detail.
The Quick Lookup Control Frames helps programmer to find the detail descriptions of every control frames.
There are three types of message in the control sessions. They are Token Frames, Control Data Frames and AudioOut Frames.
The decoder has to get the token before it sends and receives the control data and AudioOut frames. There are two types of tokens in encoders. One is control token and the other one is audio token. The authentication process has to be performed to get the tokens from encoders.
// definitions in token type in token in TOKEN_REQ #define TOKEN_TYPE_UNKNOWN 0 // unknown control token type. #define TOKEN_TYPE_CONTROL 1 // Control Data Token #define TOKEN_TYPE_AUDIO 2 // Control AudioOut Token // definitions in encryption method in Encryption in TOKEN_REQ #define ENCRYPTION_NONE 0 // no encryption algorithm is applied for response[64]. The response[64] will be the password in plain text for authentication #define ENCRYPTION_BASE64 1 // the base64 coding algorithm is applied for response[64].
The response[64] = base64(password)
Please refer to the important note below#define ENCRYPTION_MD5 2 // the md5 coding algorithm is applied for response[64].
The response[64] = md5(password)Note: Because the length of base64(password) is longer then 64 if the length of password is longer then 53 bytes, authentication fails all the time. The ENCRYPTION_BASE64 is not proper design here. Designer should not use this mechanism to protect the security. The ENCRYPTION_MD5 method helps security then. typedef struct { char name[32]; // user Name for authentication. The last character must be '\0'. Therefore, the maximum length of it is 31 int token; // token type. refer to definition of token type. see above. unsigned char rsvd[24]; // reserved. not used. fixed to 0x00s. unsigned short StreamID; // Video Streaming ID and started from 0.
In single stream encoders, this value is fixed to 0.
The stream or channel number is StreamID+1. For example, set StreamID=1 to get the stream 2 or channel 2 video.unsigned short Encryption; // Encryption method for response[64]. The supported encryption methods are listed above char response[64]; // Encryption code. see the description of the definition in encryption method } TOKEN_REQ; // definitions in token request result in status in TOKEN_REPLY #define AUTHEN_SUCCESS 0 #define AUTHEN_FAIL 1 // definitions in error code in ErrorCode in TOKEN_REPLY #define NO_ERROR 0x00000000 // success in getting a token #define ERR_ACCOUNT 0x00010001 // user name/password error #define ERR_UNKNOWN_TOKEN 0x00010002 // unknown token was requested #define ERR_DATA_TOKEN_BUSY 0x00010003 // the control data token is not available now #define ERR_AUDIO_TOKEN_BUSY 0x00010004 // the audio token is not available now #define ERR_NO_AUDIO 0x00010005 // the encoder does not have audio function typedef struct { char status; // Authentication Result. char rsvd; // Not used. fixed to 0x00 unsigned short StreamID; // Same definition as StreamID in TOKEN_REQ. int ErrorCode; // Refer to the definitions in error code. see above. int IPAddr; // IPv4 address of the decoder. In encoder, it is the same format as in_addr_t. Set it to 0 if the host (owned audio token) IP address is IPv6 address unsigned char IPv6Addr[16]; // IPv6 address of the decoder. In encoder, it is the same format as in6_addr. Set it to 0 if the host (owned audio token) IP address is IPv4 address char rsvd2[100]; // reserved. not used. fixed to 0x00s } TOKEN_REPLY; Flow of Token handshaking (Authentication)
typedef struct { unsigned char key[4]; // 4 characters key. it was fixed to key[0]='A', key[1]='C', key[2]='T', key[3]='i' unsigned short MsgType; // define it later. unsigned char ServerReply; // fixed to 0 in the frame from decoder to encoder.
fixed to 1 in the frame form encoder to decoderunsigned char StreamID; // Same definition as StreamID in TOKEN_REQ. unsigned int len; // in bytes, the length of streaming control message } CTRL_HEADER, CTRL_MSG1; typedef struct { CTRL_HEADER head; unsigned char msg[1]; // control data message. The setting in this field depends on the MsgType. } CTRL_MSG2; // definitions in control data message type in MsgType in the head of CTRL_MSG1 // ##### control data frame from decoder to encoder. the ServerReply is 0 here. ##### #define LIVE_CHECK_REQ 0x30 // Live-Check frame form decoder to encoder. No encoder's reply is needed. #define EXIT_REQ 0x31 // Decoder wants to terminate this control session. No encoder's reply is needed. #define DIO_STATUS_REQ 0x33 // Decoder asks for the encoder's DI levels. The encoder should reply it by DIO_STATUS_REPLY #define CAMERA_NAME_REQ 0x40 // Decoder asks for the encoder's camera name. The encoder should reply it by CAMERA_NAME_REPLY // definitions in control data message type in MsgType in the head of CTRL_MSG2 // ##### control data frame from decoder to encoder. the ServerReply is 0 here. ##### #define DIO_OUTOUT_REQ 0x32 // Decoder asks the encoder to change the DO levels. No encoder's reply is needed. #define SERIAL_OUT_REQ 0x36 // Decoder sends the serial command to the encoder. No encoder's reply is needed. // ##### control data frame from encoder to decoder (reply message). the ServerReply is 1 here. ##### #define DIO_STATUS_REPLY 0x33 // encoder replies the DI levels to decoder as it received the DIO_STATUS_REQ. #define CAMERA_NAME_REPLY 0x40 // encoder replies its camera name to decoder as it received the CAMERA_ANME_REQ. // ##### control data frame from encoder to decoder (notification message). the ServerReply is 1 here. ##### #define DIO_CHANGE_NOTIFY 0x34 // encoder sends the notification of changes of DI levels to all decoders whom have control data token. #define SERIAL_IN_NOTIFY 0x35 // encoder sends the notification of reception of serial input data to all decoders whom have control data token. #define AUDIO_OUT 0x37 // Decoder sends the audio data (8KHz PCM) to encoder to play out if it has a control token #define AUDIO_OUT_G711A 0x41 // Decoder sends the audio data compressed by G.711 a-law if it has a control token #define AUDIO_OUT_G711U 0x42 // Decoder sends the audio data compressed by G.711 u-law if it has a control token #define VLOSS_STATUS_REQ 0x38 // remote client could probe the video state from the encoder #define VLOSS_CHANGE_NOTIFY 0x38 // encoder sends the notification of change of video loss state to all decoders whom have control data token or response the VIDEO_STATUS_REQ. #define MOTION_STATUS_REQ 0x39 // remote client could probe the motion detection state from the encoder. #define MOTION_CHANGE_NOTIFY 0x39 // encoder sends the notification of change of motion state to all decoders whom have control data token or response the MOTION_STATUS_REQ Definition in msg[0] in CTRL_MSG2 frame for DIO control message
In the Control Message type 2 frame, the DIO_OUTPUT_REQ frame from decoder to encoder sets the DO levels in encoder based on frame's msg[0] value. Here is the format of msg[0] in these frames.
Bit in msg[0] DIO Signal bit 0 DO 1 bit 1 DO 2 bit 2 DO 3 bit 3 DO 4 bit 4 DO 5 bit 5 DO 6 bit 6 DO 7 bit 7 DO 8 The DIO_STATUS_REPLY was replied to the remote host as encoder received the DIO_STATUS_REQ frame.
As the encoder detected its DI levels were changed, it sends a DIO_CHANGE_NOTIFY frame to all decoders whom have control tokens.
The msg[0] in the DIO_STATUS_REPLY and DIO_CHANGE_NOTIFY frames record the current DI levels. Here is the format of msg[0] in these frames.
In the past, the bit 0 and bit 1 maps to DI 1 and DI2 levels and bit 4 and bit 5 maps to DO 1 and DO2 levels. However, query DO level does not make sense. We remove the DO level indication in these frame to have more room for more DIs. Here is the new bit mapping in these two frames.
Bit in msg[0] DIO Signal bit 0 DI 1 bit 1 DI 2 bit 2 DI 3 bit 3 DI 4 bit 4 DI 5 bit 5 DI 6 bit 6 DI 7 bit 7 DI 8 State Transition in DI detection and DI control message
The DI detection was controlled by the DI timer configurable by users. The encoder will not send the DIO_CHANGE_NOTIFY frame to decoders when successive DI levels where changed within the DI timer.
The DI timer controls if the encoder should send the DIO_CHANGE_NOTIFY to all decoders or not. Here is the example to show the relationship of DI state update and the DI timer.
Definition in msg[0] in CTRL_MSG2 frame for Motion control message
In the Control Message type 2 frame, the encoder sends the MOTION_CHANGE_NOTIFY frame to all decoders whom have control tokens when it found its motion states were changed. There are three motions in the encoder.
If the camera has PIR motion sensor, the MSB of msg[0] is used to indicate the PIR motion sensor state. The 1 means the motion occurs in PIR motion sensor. Otherwise, it is 0. The motion notification was controlled by the motion timer which is the same as the encoder's motion detection algorithm.
Here is the format of msg[0] in MOTION_CHANGE_NOTIFY frame.
Encoder Bitmap in msg[0] General Encoder Bit 3, 2, 1 in Msg[0] map to Motion Region 3, 2, 1
Bit 7 in Msg[0] maps to PIR motion sensorSED2300Q Bit 4, 3, 2, 1 in Msg[0] map to Motion Region 4, 3, 2, 1 ACD2000Q Single Mode Bit 1 in Msg[0] map to Motion Region 1 of Channel 1, 2, 3, 4
Client used the StreamID to identify which channel control token is requested. The firmware will update the motion detection based on the channel control token then.QUAD Mode Bit 4, 3, 2, 1 in Msg[0] map to Motion Region 4, 3, 2, 1 Sequential Mode No motion event When the corresponding bit is set, the motion region has just been triggered. Different encoders might have different motion regions. Here is the summary of motion with encoders. The bit n in msg[0] represents the motion state of motion region n-1.
Encoder Number of Motion Regions bit value when motion occurs General Encoder 3 1 SED2300Q 4 1 ACD2000Q Single Mode 1 in each channel 1 QUAD Mode 4 Sequential Mode 0 0 State Transition in Motion detection and Motion control message
The Motion detection was controlled by the motion trigger timer configurable by users. The encoder will not send the MOTION_CHANGE_NOTIFY frame to decoders when successive Motion states where changed within the motion trigger timers.
Motion states update with Motion Trigger Timer
There are three motion trigger timers in the encoders. These motion trigger timers are independent and configurable by users. Every motion region owns its motion trigger timer. The encoder will not send the MOTION_CHANGE_NOTIFY to all decoders when the motion state were changed if the motion trigger timer is not expired. Here is the example to show the relationship of motion state update and the motion trigger timer for a motion region.
If there is a PIR motion sensor, the PIR motion timer is configurable by users. The function of PIR motion timer is similar to encoder motion timer.
Important Note
The motion state will no be changed when the motion is still trigger as the motion trigger timer is expired. That means the encoder will NOT send the any motion notification message to decoder in this case.Motion states update in dual streaming encoders
In PlatformT and PlatformK, the motion detection is only available in stream 1. However, these two streams use the same video source. To have motion event in stream 2, the firmware has to update the motion detection results in stream 1 to the stream 2.
Definition in msg[0] in CTRL_MSG2 frame for Video Loss control message
In the Control Message type 2 frame, the encoder sends the VLOSS_CHANGE_NOTIFY frame to all decoders whom have control tokens when it found its video states were changed. Here is the summary of video loss control message with encoders.
Encoder Bits used in msg[0] bit value when video was locked General Encoder bit 0 1 SED2300Q bit 0,1,2,3 0 ACD2000Q Single Mode Bit 0 in Msg[0] map to video loss state of Channel 1, 2, 3, 4
Client used the StreamID to identify which channel control token is requested. The firmware will update the video loss state based on the channel control token then.1 QUAD Mode bit 0,1,2,3 map ch1,ch2,ch3,ch4 1 Sequential Mode bit 0,1,2,3 map ch1,ch2,ch3,ch4 The StreamID in the control session is fixed to 0. The behavior is the same as QUAD mode 1 Definition in msg[n] in CTRL_MSG2 frame for Serial Data message
In the Control Message type 2 frame, the decoder sends serial command to encoder through SERIAL_OUT_REQ frame. The msg[ ] in the frame carried the serial command. The maximum length of every serial command should not exceed 31 bytes.
The encoder updates the reception of serial input data to all decoders whom have control tokens through the SERIAL_IN_NOTIFY frame. The msg[n] in the frame carried the encoder's serial data.
Definition in msg[n] in CTRL_MSG2 frame for Camera Name message
The encoder replies the decoder's CAMERA_NAME_REQ by CAMERA_NAME_REPLY. The encoder's camera name settings will be carried by msg[n] in CAMERA_NAME_REPLY frame.
Once the decoder got the audio token successfully, it could stream the audio data to the encoder through the AUDIO_PLAY_REQ frame. The format of this frame is CTRL_MSG2 where the MsgType is 0x37. The msg[n] in the frame contains the audio raw data encoded by 8KHz, 16 bit in width PCM. The length of the audio raw data in every AUDIO_PLAY_REQ is 4096 bytes. As the encoder received this frame, it decoded the audio data in msg[n] without any reply.
In PlatformA and PlatformK QUAD Video Servers, the motion detection and video loss events are different from their streaming modes. In PlatformK camera, the motion detection behavior is different from its streaming modes. Every channel has its own motion detection and video loss events. But, DIO, serial port and audio are shared in all channels/streams. Therefore, we focus on the motion detection and video loss events in this section.
QUAD Video Server
- Single Mode
Four channels are available in this mode. The client has to use StreamID to request the specific channel's control token. The video server based on this StreamID to link corresponding channel's motion detection and video loss state. Client could tell the event is from which channel by reading the StreamID in video server notification packet.
30 control tokens are shared in these four channels.
- QUAD Mode
Only four channel in one stream is available in this mode. Motion detection and video loss events are global events. Video Server ignores the StreamID in the client's token request. However, the StreamID should be 0 in the token request packet.
Every change of motion detection and video loss in every channel makes video server sends the notification packets. The StreamID in video server notification packets should be 0.
- Sequential Mode
Video server sends the channel 1, 2, 3, 4 sequentially. The StreamID in this mode is not used and should be fixed to 0. Because video server streams these four channels in a single video session, we treads these four channels as a single stream. Therefore, the notification of motion detection and video loss is the same as QUAD mode.PlatformK Camera
- Single Stream Mode
In this mode, the handles of control messages are the same as general camera.
- Dual Streams Mode
In this mode, the motion detection notification is the same as PlatformT camera.
- 4 Streams Mode
Every stream has one motion detection region. The notification of motion detection is the same as the SINGLE mode in QUAD video server. The client has to use StreamID to request the specific stream's control token. The video server based on this StreamID to link corresponding stream's motion detection in runtime. Client could tell the event is from which stream by reading the StreamID in camera notification packets.
30 control tokens are shared in these four streams.
Frame MsgType ServerReply Massage in the Frame Description TOKEN_REQ None 0 Name, Token Type, Stream ID, Encryption Method, Response Request for Token (authentication) TOKEN_REPLY None 1 Status, Error Code, Stream ID, Decoder IP Address Reply the TOKEN_REQ frame LIVE_CHECK_REQ 0x30 0 Format is CTRL_MSG1 Keep the Control Data Session alive. No encoder's reply is needed EXIT_REQ 0x31 0 Format is CTRL_MSG1 Decoder wants to terminate this control session. No encoder's reply is needed. DIO_STATUS_REQ 0x33 0 Format is CTRL_MSG1 Decoder asks for the encoder's DI levels. The encoder will reply it by DIO_STATUS_REPLY CAMERA_NAME_REQ 0x40 0 Format is CTRL_MSG1 Decoder asks for the encoder's camera name. The encoder will reply it by CAMERA_NAME_REPLY. DIO_OUTOUT_REQ 0x32 0 DO Levels. Format is CTRL_MSG2 Decoder asks the encoder to change the DO levels. No encoder's reply is needed SERIAL_OUT_REQ 0x36 0 Serial Command. Format is CTRL_MSG2 Decoder sends the serial command to the encoder. No encoder's reply is needed. DIO_STATUS_REPLY 0x33 1 DI Levels. Format is CTRL_MSG2 encoder replies the DI levels to decoder as it received the DIO_STATUS_REQ. CAMERA_NAME_REPLY 0x40 1 Camera Name. Format is CTRL_MSG2 encoder replies its camera name to decoder as it received the CAMERA_ANME_REQ. DIO_CHANGE_NOTIFY 0x34 1 DI Levels. Format is CTRL_MSG2 encoder sends the notification of changes of DI levels to all decoders whom have control data token. SERIAL_IN_NOTIFY 0x35 1 Serial Input Data. Format is CTRL_MSG2 encoder sends the notification of reception of serial input data to all decoders whom have control data token. AUDIO_OUT 0x37 0 Audio Out Data, Format is CTRL_MSG1 Decoder sends the audio date (8KHz PCM) if it has a control token. VLOSS_STATUS_REQ 0x38 0 Video State. Format is CTRL_MSG1 Decoder asks for the encoder's VLOSS status. VLOSS_CHANGE_NOTIFY 0x38 1 Video State. Format is CTRL_MSG2 encoder sends the notification of change of video loss state to all decoders whom have control data token or response the VLOSS_STATUS_REQ to decoder MOTION_STATUS_REQ 0x39 1 Motion State. Format is CTRL_MSG1 Decoder asks the encoder motion status. MOTION_CHANGE_NOTIFY 0x39 1 Motion State. Format is CTRL_MSG2 encoder sends the notification of change of motion state to all decoders whom have control data token.
There are several states in the encoder and decoder to handle the control events and AudioOut data. The state transition helps to describe the behavior (protocol) of handling these events and data in encoder and decoder.
State Machine in Encoder
- Transition State Diagram
- There is only one audio token and 10 control tokens in the Encoder. Therefore, the encoder will reject token requests when the token was not available.
- In control data session, the encoder has a timer to monitor if there is no any transaction in control session. If this timer is expired, the encoder will close this control connection. Any successful data transaction will reset this timer. Therefore, if there is no data from encoder, the decoder has to send the Live-Check packet to the encoder to keep this connection alive. This mechanism is so-called Live-Check mechanism. The maximum time in this timer is called Life-Check Time.
- In AudioOut data session, the decoder does NOT need to send the Live-Check packet to the encoder because the AudioOut data is generated constantly. The encoder should receive the AudioOut data with constant data rate. If the encoder does not receive the AudioOut frame in the Live-Check Time, the AudioOut data session will be closed by Encoder.
- Timing Parameters
Item Maximum time in second Description Live-Check Timer 30 Maximum allowable idle time in control data session
- Video/Audio Session Error means there is anything wrong in handling the Video/Audio data in the streaming session. For example, the streaming socket errors.
- The network socket will be closed and re-issue a new socket connection when the state moves to Start state from another state.
- The Timeout event depends on the timing parameters in every state. The maximum values of these timing parameters were listed below.
Item Maximum time in second Description Connection Timer 10 TCP 3-Way Handshaking Timer Token Timer 5 Control and Audio Token Timer Data Sending Timer 5 Timer for sending Control message/AudioOut frames
- "CONTROL TO SERVER_IP FAIL, WAN_IP" when there is anything wrong in the control session. For example, the fail of getting control token, fail of sending control data to encoder.
- "AUDIO OUT TO SERVER_IP FAIL, WAN_IP" when there is anything wrong in the control AudioOut session. For example, the fail of getting audio token, fail of sending audio data to encoder.
- "CONTROL AND AUDIO OUT TO SERVER_IP, WAN_IP" when the case 1 and case 2 in above occur at the same time.
Streaming Protocol in TCP 2.0, Function Availability with Platform Firmware