Control Session Design Specification

Version v1.1.03

Description

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.

Topology

Message Format

There are three types of message in the control sessions. They are Token Frames, Control Data Frames and AudioOut Frames.

Token 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)

Control Data Frames

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 decoder
	unsigned 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 sensor
SED2300Q		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.

AudioOut Frames

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.

Control token in QUAD Video Servers and 4 streams mode in PlatformK

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.

Quick Lookup Control Messages

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.

Connection Management

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

State Machine in Decoder

• Transition State Diagram

• 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.

• Timing Parameters

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

• Error Message in OSD for Decoder

1. "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.
2. "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.
3. "CONTROL AND AUDIO OUT TO SERVER_IP, WAN_IP" when the case 1 and case 2 in above occur at the same time.

See Also

Streaming Protocol in TCP 2.0, Function Availability with Platform Firmware

Back to

HOME