WebsocketServer Class Reference

#include <WebsocketServer.hh>

Public Member Functions
	WebsocketServer ()=default
	Constructor.
virtual	~WebsocketServer ()
	Destructor.
void	Configure (const Entity &_entity, const std::shared_ptr< const sdf::Element > &_sdf, EntityComponentManager &_ecm, EventManager &_eventMgr) final
	Documentation inherited.
void	OnConnect (int _socketId)
	Callback that is triggered when a new connection is established.
void	OnDisconnect (int _socketId)
	Callback that is triggered when a connection ended.
void	OnMessage (int _socketId, const std::string _msg)
	Handles incoming websocket messages.
void	Run ()
bool	UpdateMsgTypeSubscriptionCount (const std::string &_topic, int _socketId, bool _subscribe)
	Check and update subscription count for a message type. If a client has more subscriptions to a topic of a specified type than the subscription limit, this will block subscription. On the other hand, for an unsubscription operation, the count is decremented.
Public Member Functions inherited from System
	System ()=default
	Constructor.
virtual	~System ()=default
	Destructor.
Public Member Functions inherited from ISystemConfigure
virtual	~ISystemConfigure ()=default

Public Attributes
std::map< int, std::unique_ptr< Connection > >	connections
	All of the websocket connections.
int	maxConnections {-1}
	The maximum number of connections. A negative number indicates no limit.
int	messageCount {0}
	Number of pending messages. This is used to throttle the run loop.
std::map< std::string, int >	msgTypeSubscriptionLimit
	The limit placed on the number of subscriptions per msg type for each connection. The key is the msg type, e.g. gz.msgs.Image, and the value is the subscription limit.
std::mutex	mutex
int	queueSizePerConnection {-1}
	The message queue size per connection. A negative number indicates no limit.
std::condition_variable	runConditionVariable
	Run loop condition variable.
std::mutex	runMutex
	Run loop mutex.
std::mutex	subscriptionMutex
	A mutex used in the OnWebsocketSubscribedMessage function.
std::map< std::string, std::set< int > >	topicConnections
	All of the subscribed Gazebo topics. The key is the topic name, and the value is the set of websocket connections that have subscribed to the topic.

Additional Inherited Members
Public Types inherited from System
using	PriorityType = int32_t
	Signed integer type used for specifying priority of the execution order of PreUpdate and Update phases.
Static Public Attributes inherited from System
static constexpr PriorityType	kDefaultPriority = {0}
	Default priority value for execution order of the PreUpdate and Update phases.
static constexpr std::string_view	kPriorityElementName
	Name of the XML element from which the priority value will be parsed.

Detailed Description

A websocket server for gzweb

Plugin parameters

• <publication_hz> : An integer that is the maximum publication hertz rate.
• <port> : An integer that is websocket port.
• <authorization_key> : A key used for authentication. If this is set, then a connection must provide the matching key using an "auth" call on the websocket. If the <admin_authorization_key> is set, then the connection can provide that key.
• <admin_authorization_key> : An admin key used for authentication. If this is set, then a connection must provide the matching key using an "auth" call on the websocket. If the <authorization_key> is set, then the connection can provide that key.
• <max_connections> : An integer that specifies the maximum number of active websocket connections. A value less than zero indicates an unlimited number, this is the default. A websocket client error code of 1008 along with a reason set to "max_connections" will be returned if a new connection is rejected due to the max connection threshold.
• <ssl> : Element that contains SSL configuration. For testing purposes you can create self-signed SSL certificates. Run

  openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout server.key \
      -out server.cert

  Use "localhost" for the "Common Name" question. If you are testing with a browser, first navigate to "https://localhost:<port>" and accept the self-signed certificate.
  • <cert_file>: Child element of <ssl> that contains the path to the SSL certificate file.
  • <private_key_file>: Child element of <ssl> that contains the path to SSL private key file.

Websocket Server Interface

The websocket server listens for incoming requests and sends messages based on the requests.

All messages on the websocket, incoming and outgoing, are structured in a frame that consists of four comma separated components:

1. operation: string,
2. topic_name: string,
3. message_type: string, and
4. payload: serialized data.

The operation component is mandatory and must be one of:

1. "sub": Subscribe to the topic in the topic_name component,
2. "pub": Publish a message from the Gazebo Transport topic in the topic_name component,
3. "topics": Get the list of available topics,
4. "topics-types": Get the list of available topics and their message types,
5. "protos": Get a string containing all the protobuf definitions, and
6. "particle_emitters": Get the list of particle emitters. definitions.
7. "unsub": Unsubscribe from the topic in the topic_name component
8. "asset": Get a file as a byte array from a running Gazebo server. Set the payload to the file URI that is being requested.
9. "worlds": Get world info.
10. "scene": Get scene info.
11. "image": Subscribe to an image in the topic_name component.
12. "throttle": Throttle a topic in the topic_name component by the rate in the payload component.
13. "req": Request a service, passing in the optional request message. The payload should be a serialized protobuf message. The response payload holds the serialized protobuf response, if any.

The topic_name component is mandatory for the "sub", "pub", "unsub", and "req" operations. If present, it must be the name of a Gazebo Transport topic.

The message_type component is mandatory for the "pub" and "req" operations. If present it names the Gazebo Message type, such as "gz.msgs.Clock".

The payload component is mandatory for the "pub" and "req" operations. If present, it contains a serialized string of a Gazebo Message.

Example frames

1. Get the list of topics: topics,,,
2. Get the protobuf definitions: protos,,,
3. Subscribe to the "/clock" topic: sub,/clock,,
4. Websocket server publishing data on the "/clock" topic: pub,/clock,gz.msgs.Clock,<serialized_data>

Example usage

Websocket Server

1. Add the following to the top of an SDF file to include the websocket server system when launching a world.

   <plugin name="WebsocketServer" filename="gz-sim-websocket-server-system">

   <publication_hz>30</publication_hz> </plugin>

2. Launch your SDF world file, e.g.

gz sim -v 4 -s websocket.sdf

1. Connect gzweb to the websocket server for web visualization. An example is provided in examples/scripts/websocket_server

Constructor & Destructor Documentation

WebsocketServer()

WebsocketServer ( )

default

Constructor.

~WebsocketServer()

virtual ~WebsocketServer ( )

virtual

Destructor.

Member Function Documentation

Configure()

void Configure ( const Entity &  _entity, const std::shared_ptr< const sdf::Element > &  _sdf, EntityComponentManager &  _ecm, EventManager &  _eventMgr  )

finalvirtual

Documentation inherited.

Implements ISystemConfigure.

OnConnect()

void OnConnect

(

int

_socketId

)

Callback that is triggered when a new connection is established.

Parameters

[in]

_socketId

ID of the socket.

OnDisconnect()

void OnDisconnect

(

int

_socketId

)

Callback that is triggered when a connection ended.

Parameters

[in]

_socketId

ID of the socket.

OnMessage()

void OnMessage	(	int	_socketId,
		const std::string	_msg
	)

Handles incoming websocket messages.

Parameters

[in]	_socketId	Id of the socket associated with the message.
[in]	_msg	The incoming message.

Run()

void Run

(

)

UpdateMsgTypeSubscriptionCount()

bool UpdateMsgTypeSubscriptionCount	(	const std::string &	_topic,
		int	_socketId,
		bool	_subscribe
	)

Check and update subscription count for a message type. If a client has more subscriptions to a topic of a specified type than the subscription limit, this will block subscription. On the other hand, for an unsubscription operation, the count is decremented.

Parameters

[in]	_topic	Topic to subscribe to or unsubscribe from
[in]	_socketId	Connection socket id
[in]	_subscribe	True for subscribe operation, false for unsubscribe operation

Returns

True if the subscription count is incremented or decremented, and false to indicate the subscription limit has reached.

Member Data Documentation

connections

std::map<int, std::unique_ptr<Connection> > connections

All of the websocket connections.

maxConnections

int maxConnections {-1}

The maximum number of connections. A negative number indicates no limit.

messageCount

int messageCount {0}

Number of pending messages. This is used to throttle the run loop.

msgTypeSubscriptionLimit

std::map<std::string, int> msgTypeSubscriptionLimit

The limit placed on the number of subscriptions per msg type for each connection. The key is the msg type, e.g. gz.msgs.Image, and the value is the subscription limit.

mutex

std::mutex mutex

queueSizePerConnection

int queueSizePerConnection {-1}

The message queue size per connection. A negative number indicates no limit.

runConditionVariable

std::condition_variable runConditionVariable

Run loop condition variable.

runMutex

std::mutex runMutex

Run loop mutex.

subscriptionMutex

std::mutex subscriptionMutex

A mutex used in the OnWebsocketSubscribedMessage function.

topicConnections

std::map<std::string, std::set<int> > topicConnections

All of the subscribed Gazebo topics. The key is the topic name, and the value is the set of websocket connections that have subscribed to the topic.

---

The documentation for this class was generated from the following file:

• WebsocketServer.hh