SETP/CICPv2 Draft 0.2

Low level transport protocol is UDP. Each UDP packet may contain one or more frames. Most messages will have length of just one frame.

Statistics

Protocol has currently total of 38 messages defined:

• 3 client to server connection messages
• 3 simulation to simulation connection messages
• 4 connection control messages
• 2 implementation validation messages
• 4 client to server query messages (avatars and simulations)
• 3 client to simulation joining messages
• 20 simulation messages (queries, perceptions, interactions, handovers and injections)

UDP Packet Data Structure

UDP packet data length is maximum of (1500-48(IPv6))=1452 bytes which consists of header bytes and as many frames as fit in the remaining bytes.

packet header (18 bytes) - message frames

• 4 - session id: Session id assigned by answering party (UINT)
• 4 - packet id: Packet id(UINT)
• 8 - first send time: Time the packet was sent for the first time. (TIMESTAMP)
• 1 - quaranteed: Whether this is guaranteed and ACK is expected. (UBYTE)
• 1 - resend count: Count of resends. (UBYTE)

Frame Structure (maximum 256 bytes)

frame header (10 bytes) - frame data (maximum 246 bytes)

frame header:

• 1 - type: Type index from message type table. (UBYTE)
• 4 - message id: Message id assigned by the sender. Overflows periodically. (UINT)
• 2 - frame count: Number of frames in this message. (USHORT)
• 2 - frame index: Index of the message part for long messages spanning over multiple packets. (USHORT)
• 1 - frame data size (0-246)

Largest message data sizes are limited to by maximum frame count and frame data size to ~15Mbytes. Could this protocol be used for transmitting larger amounts of data on background? If so another message type can be specified for large file transfers where each message transmit part of the file.

Connection Control Messages

Disconnect Notification

quaranteed: 1

data: -

Keepalive

guaranteed: 1

data: -

Acknowledgement

guaranteed: 0

data:

• 4- acknowledged upd packet id (Repeated 1-64 times) (ULONG(s))

Throttling Notification

guaranteed: 1

data:

• 4 - bytes per second. Number of bytes per second sender is ready to receive. (UINT)

Implementation Validation Messages

Challenge Request

guaranteed: 1

data:

• 64 - Challenge request bytes. (DATA)

Challenge Response

guaranteed: 1

data:

• 64 - Challenge response bytes. (DATA)

Client to Server Connecting Messages

Connect Request

guaranteed: 1

session id: - (no session id in connect. Session id is returned in first frame from server which is always ACK.)

data:

• 60 - client program name (STRING)
• 1 - client program major version (UBYTE)
• 1 - client program minor version (UBYTE)
• 1 - protocol major version (UBYTE)
• 1 - protocol minor version (UBYTE)
• 32 - user identifier (uuid or user name) (UUID/STRING)
• 32 - user passphrase (authentication session uuid or password) (UUID/STRING)

Server responds with disconnect if credentials are incorrect or suitable encoding is not found and with connect response if credentials were correct. Simple implementations may create accounts on the fly. Advanced servers may offer web interface for account management.

Connect Success Response

guaranteed: 1

data:

• 32 - server name (STRING)
• 28 - server program name (STRING)
• 1 - server program major version (UBYTE)
• 1 - server program minor version (UBYTE)
• 1 - protocol major version (UBYTE)
• 1 - protocol minor version (UBYTE)
• 64 - bubble cloud url (STRING)
• 64 - media repository url (STRING)
• 16 - media packet id (UUID)
• 1 - media packet major version (UBYTE)
• 1 - media packet minor version (UBYTE)

Connect Failure Response

guaranteed: 1 data:

• 32 - server short description (STRING)
• 28 - server program name (STRING)
• 1 - server program major version (UBYTE)
• 1 - server program minor version (UBYTE)
• 1 - protocol major version (UBYTE)
• 1 - protocol minor version (UBYTE)
• 1 - failure code (0 - authentication failed, 1 - not authorized, 2 - unsupported client implementation or version, 3 - unsupported protocol version) (UBYTE)

Client to Server Query Messages

List Bubbles Request

guaranteed: 1

data: -

List Bubbles Response

guaranteed: 1

data: Entries repeat as many times as there are bubbles.

• 16 - bubble identifier (UUID)
• 48 - simulation short description. (STRING)

This message may be split to multiple frames.

List Avatars Request

guaranteed: 1

data:

• 16 - simulation identifier: Bubble identifier. (UUID)

List Avatars Response

guaranteed: 1

data: Entries repeat as many times as there are avatars.

• 16 - avatar identifier: Avatar identifier. (UUID)
• 16 - avatar model identifier. (UUID)
• 32 - avatar short description.

This message may be split to multiple frames.

Client to Simulation Joining Messages

Join Bubble Request

guaranteed: 1

data:

• 16 - bubble identifier (UUID)
• 16 - avatar identifier (UUID)

Join Bubble Response

guaranteed: 1 data:

• 1 - success: Success of the join. (1 or 0) (UBYTE)

Leave Bubble Notification

guaranteed: 1 data: -

This notification can be sent by either party to nofity other about client detaching from the simulation. The operation will always work.

Simulation to Simulation Connection Messages

Bubble Link Request Message

guaranteed: 1

session id: - (no session id in connect. Session id is returned in first frame from server which is always ACK.)

data:

• 60 - calling server program name (STRING)
• 1 - calling server program major version (UBYTE)
• 1 - calling server program minor version (UBYTE)
• 1 - protocol major version (UBYTE)
• 1 - protocol minor version (UBYTE)
• 64 - calling cloud url (STRING)
• 16 - calling bubble id (UUID)
• 16 - target bubble identifier (UUID)
• 12 - relative location of calling bubble center (answering bubble coordinate space)(vector3(FLOAT))
• 4 - bubble range (FLOAT)
• 4 - bubble perception range (FLOAT)
• 4 - simulation cycle length (microseconds) (UINT)

Two different cloudscan also link. In this case linking volume should be limited to be between two bubbles and cloud portal volume should be clearly marked in the virtual environment.

Bubble Link Success Response Message

guaranteed: 1

data:

• 64 - cloud url (STRING)
• 44 - answering server program name (STRING)
• 1 - answering server program major version(UBYTE)
• 1 - server program minor version(UBYTE)
• 1 - protocol major version(UBYTE)
• 1 - protocol minor version(UBYTE)
• 4 - bubble range (FLOAT)
• 4 - bubble perception range (FLOAT)
• 4 - simulation cycle length (microseconds) (UINT)
• 4 - Number of linked bubbles

<-- Frame Changes -->

The following fields area repeated for each existing linked simulation N times.

• 16 - bubble id (UUID)
• 88 - Address
• 4 - Port
• 12 - relative location of bubble center (vector3(FLOAT))
• 4 - bubble range (FLOAT)
• 4 - bubble perception range (FLOAT)

Bubble Link Failure Response Message

data:

• 64 - cloud url (STRING)
• 28 - answering server program name (STRING)
• 1 - answering server program major version(UBYTE)
• 1 - server program minor version(UBYTE)
• 1 - protocol major version(UBYTE)
• 1 - protocol minor version(UBYTE)
• 1 - error code (0 - unauthorized, 1 - unsupported server implementation or version, 2 - unsupported protocol version) (UBYTE)

Simulation Messages

Object Examine by ID

guaranteed: 1

• 16 - object identifier (UUID)

Response will consists of object observation and if required movement and animation observations.

Object Examine by Index

guaranteed: 1

• 4 - object index (Zero based index to table of objects known to server.)

Response will consists of object observation and if requid animation observations.

Object Perception

guaranteed: 1

• 16 - object identifier (UUID)
• 16 - type identifier (UUID)
• 16 - model identifier (UUID)
• 16 - simulation identifier (UUID)
• 4 - object index (Zero based index to table of objects known to server.)
• 4 - bounding sphere radius (FLOAT)
• 4 - mass (FLOAT)
• 12 - location (vector3) (FLOAT,FLOAT,FLOAT)
• 12 - velocity (vector3) (FLOAT,FLOAT,FLOAT)
• 12 - acceleration (vector3) (FLOAT,FLOAT,FLOAT)
• 16 - orientation (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT)
• 16 - angular velocity (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT)
• 16 - angular acceleration (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT)
• 4 - object internal data length (UINT)
• X - object internal data (As long as needed may cause message to be splitted to several frames) (DATA)

Movement Perception

guaranteed: 0 or 1 (periodic observations (signals) need not be guaranteed) data:

• 4 - object index
• 12 - location (vector3) (FLOAT,FLOAT,FLOAT)
• 12 - velocity (vector3) (FLOAT,FLOAT,FLOAT)
• 16 - orientation (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT)

Advanced Movement Perception

guaranteed: 0 or 1 (periodic observations (signals) need not be guaranteed) data:

• 4 - object index
• 12 - location (vector3) (FLOAT,FLOAT,FLOAT)
• 12 - velocity (vector3) (FLOAT,FLOAT,FLOAT)
• 16 - orientation (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT)
• 16 - angular velocity (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT)
• 12 - acceleration (vector3) (FLOAT,FLOAT,FLOAT)
• 16 - angular acceleration (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT)

Send when acceleration changes and at ~10 seconds intervals.

Animation Perception

guaranteed: 0 or 1 (periodic observations (signals) need not be guaranteed) data:

• 4 - object index
• 2 - number of animations executing.

The following are repeated X times.

• 4 - animation identifier
• 4 - animation length (milliseconds) (UINT)
• 4 - animation phase (milliseconds) (UINT)
• 1 - animation state (0=halted, 1=run once, 2 repeat)
• 3 - padding

Disappearence Perception

guaranteed: 1

• 4 - object index

Collision Perception

guaranteed: 1

• 4 - source object index
• 4 - target object index

Collision notification is sent when two dynamic objects collide and they are simulated by different simulations. When either simulation detects collision it calculates collision response to the object it owns and sends collision notification to the other simulation. When simulation receives a collision notification it calculates the collision response to the object it owns unless it has already detected the collision.

Interaction Request

guaranteed: 1

• 18 - action name (STRING)
• 1 - target type : (0: self, 1: object, 2: location, 3: direction, 4 volume) (UBYTE)
• 1 - is data public: (1 or 0) (UBYTE)
• 4 - source object index
• 4 - target object index
• 4 - volume sphere radius (FLOAT)
• 12 - location (vector3) (FLOAT,FLOAT,FLOAT)
• 4 - action request data length (UINT)
• X - action request data (As long as needed. May cause message to be splitted to several frames.) (DATA)

Interaction Response

guaranteed: 1

• 4 - message id
• 1 - success (1 or 0)
• 124 - failure message (STRING)
• 4 - action response data length (UINT)
• X - action response data (DATA)

Interaction Perception

guaranteed: 1

• 18 - action name (STRING)
• 1 - target type : (0: self, 1: object, 2: location, 3: direction, 4 volume) (UBYTE)
• 1 - is data public: (1 or 0) (UBYTE)
• 4 - source object index
• 4 - target object index
• 4 - volume sphere radius (FLOAT)
• 12 - location (vector3) (FLOAT,FLOAT,FLOAT)
• 4 - action request data length (UINT)
• X - action request data (No data if data is private.) (DATA)
• 4 - action response data length (UINT)
• X - action response data (DATA)

Handover Request

guaranteed: 1

• 16 - object identifier (UUID)
• 12 - source location (vector3) (FLOAT,FLOAT,FLOAT)
• 12 - target location (vector3) (FLOAT,FLOAT,FLOAT)
• 8 - object internal data length (ULONG)
• 16 - source simulation identifier (UUID)
• 16 - target simulation identifier (UUID)
• 4 - object internal data length
• X - object internal data (As long as needed. May cause message to be splitted to several frames.)

Handover is a process where object is handed over from one bubble to another bubble.

Handover Response

guaranteed: 1

• 4 - message id
• 1 - success (1 or 0)
• 124 - failure message (STRING)

Handover Perception

guaranteed: 1

• 16 - object identifier (UUID)
• 12 - source location (vector3) (FLOAT,FLOAT,FLOAT)
• 12 - target location (vector3) (FLOAT,FLOAT,FLOAT)
• 16 - source simulation identifier (UUID)
• 16 - target simulation identifier (UUID)

Injection Request

guaranteed: 1

• 16 - object identifier (UUID)
• 16 - type identifier (UUID)
• 16 - model identifier (UUID)
• 16 - simulation identifier (UUID)
• 4 - object index (Zero based index to table of objects known to server.)
• 4 - bounding sphere radius (FLOAT)
• 4 - mass (FLOAT)
• 12 - location (vector3) (FLOAT,FLOAT,FLOAT)
• 12 - velocity (vector3) (FLOAT,FLOAT,FLOAT)
• 12 - acceleration (vector3) (FLOAT,FLOAT,FLOAT)
• 16 - orientation (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT)
• 16 - angular velocity (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT)
• 16 - angular acceleration (quaternion) (FLOAT,FLOAT,FLOAT,FLOAT)
• 4 - object internal data length (UINT)
• X - object internal data (As long as needed may cause message to be splitted to several frames) (DATA)

Injection is a process where participant injects an object to a bubble. Injected object is governed by the participant and all interaction requests should be forwarded to it.

Injection Response

guaranteed: 1

• 4 - message id
• 1 - success (1 or 0)
• 124 - failure message (STRING)

Ejection Request

guaranteed: 1

• 16 - object identifier (UUID)

Ejection is a process where participant ejects object it owns from the world.

Ejection Response

guaranteed: 1

• 4 - message id
• 1 - success (1 or 0)
• 124 - failure message (STRING)