Library API#

Library to access messages exchanged between processes: Flight supervisor, Guidance, Drone controller and Ground SDK.

They are described using Protocol Buffers and a small wrapper on top to define services with commands and events. Messages are transferred using unix sockets on the drone. A tunnel is also provided to the mission UI through Ground SDK to exchange messages for the mission specific code.

An example on how to use this library is provided in the hello.py of the “Hello, Drone!” Flight mission.

class Message#

Class wrapping a message consisting of a 32-bit Id and a payload. The 32-bit Id is split in 2 fields

  • high 16-bit: service Id. Used to route messages in the system

  • low 16-bit: message number. Used to route message in a service

Public Functions

Message()#

Default constructor, initialize the Id to 0 and an empty payload.

Message(uint32_t msgId, const void *data, uint32_t len)#

Constructor.

Remark

no copy of the buffer payload is done, the caller shall ensure it stays valid when this message is used.

Parameters:

  • msgId – 32-bit Id of the message.

  • data – data buffer of the payload.

  • len – size of the payload.

~Message()#

Destructor. The buffer of the payload is freed only if this object is the owner of the data (see clone method).

inline uint32_t getMsgId() const#

Get the Id of the message.

Returns:

32-bit Id of the message.

inline uint16_t getServiceId() const#

Get the service Id of the message.

Returns:

16-bit service of the message (high 16-bit of the message Id).

inline uint16_t getMsgNum() const#

Get the message number of the message.

Returns:

16-bit message number of the message (low 16-bit of the message Id).

inline const void *getData() const#

Get the data buffer of the message payload.

Returns:

data buffer of the message payload.

inline uint32_t getLen() const#

Get the size of the message payload.

Returns:

size of the message payload.

inline uint32_t getFdCount() const#

Get the number of attached file descriptors.

Returns:

number of attached file descriptors.

inline int getFd(uint32_t i) const#

Get an attached file descriptor.

Remark

no new ownership si transferred. the fd will be valid as long as the message is valid. Either clone the message or ‘dup’ the fd to get an extra lifetime.

Parameters:

i – index of the fd to retreive (0..MAX_FD_COUNT-1).

Returns:

file descriptor or -1 if none attached in the slot.

int addFd(int fd)#

Attach a new fd to the message.

Remark

no new ownership is transferred, the fd shall be valid as mlong as the message is valid.

Parameters:

fd – file descriptor to attach

Returns:

0 in case of success, negative errno in case of error.

Message *clone() const#

Close this message by allocating a new object and copy the internal payload. The returned message will own the copied payload

Returns:

copy of this message.

Public Members

int fd#
bool owned#

Public Static Attributes

static const uint32_t MAX_FD_COUNT = 4#

Maximum number of file descriptors that can be passed with the message

class MessageSender#

Base class to send messages to peer. The sender shall first be attached to a MessageHub instance to be able to send messages.

Public Functions

MessageSender(const std::string &serviceName)#

Constructor.

Parameters:

serviceName – service name. Used to get the associated service Id.

virtual ~MessageSender()#

Destructor.

inline const std::string &getServiceName() const#

Get the service name.

Returns:

service name.

virtual int send(const Message &msg, pomp::Connection *conn = nullptr)#

Send a message.

Parameters:

  • msg – message to send.

  • conn – remote connection to target. If nullptr, it will broadcast the message to all peers connected to the associated channel.

Returns:

0 in case of success, negative errno in case of error.

virtual int send(uint16_t msgNum, const void *data, uint32_t len, pomp::Connection *conn = nullptr)#

Send a message.

Parameters:

  • msgNum – message number. The full message Id will be computed using the service Id itself computed from the service name.

  • data – data buffer of the payload.

  • len – size of the payload.

  • conn – remote connection to target. If nullptr, it will broadcast the message to all peers connected to the associated channel.

Returns:

0 in case of success, negative errno in case of error.

virtual int send(uint16_t msgNum, const google::protobuf::MessageLite &msgLite, pomp::Connection *conn = nullptr)#

Send a message.

Parameters:

  • msgNum – message number. The full message Id will be computed using the service Id itself computed from the service name.

  • msgLite – message to send as a protobuf object. This method will serialize the message and send it.

  • conn – remote connection to target. If nullptr, and it will broadcast the message to all peers connected to the associated channel.

Returns:

0 in case of success, negative errno in case of error.

bool hasPeers()#

Indicate if one or more peers is connected to this sender

Remark

this can be used to avoid creating useless messages

Returns:

true if the sender is attached to a channel which has has at least one peer

class MessageHandler#

Base class to receive message from a peer. The handler shall first be attached to a MessageHub instance to be able to receive messages.

Public Functions

MessageHandler(const std::string &serviceName)#

Constructor.

Parameters:

serviceName – service name. Used to get the associated service Id.

virtual ~MessageHandler()#

Destructor.

inline const std::string &getServiceName() const#

Get the service name.

Returns:

service name.

virtual void handle(const Message &msg) = 0#

Function called to handle/process the message.

class MessageHub#

Central object where all communication channels (servers/clients) are created and all senders/handlers are attached to send/receive messages.

Public Functions

MessageHub(pomp::Loop *pompLoop, ConnectionHandler *connectionHandler)#

Constructor.

Parameters:

  • pompLoop – ‘pomp’ Loop object to use for internal sockets.

  • connectionHandler – optional ConnectionHandler object to be notified of connections/disconnections of channels.

~MessageHub()#

Destructor

Channel *startServerChannel(const pomp::Address &addr, uint32_t mode = 0)#

Create and start a server channel.

Parameters:

  • addr – address to listen to.

  • mode – optional access mode for unix sockets. If not set the socket will be created with default access depending on the current value of UMASK(2).

Returns:

Channel object that can then be used to attach senders/handlers.

Channel *startClientChannel(const pomp::Address &addr)#

Create and start a client channel.

Parameters:

addr – address to listen to.

Returns:

Channel object that can then be used to attach senders/handlers.

void stop()#

Stop and destroy all channels.

int enableDump(Channel *channel = nullptr)#

Enable the dump of sent/received messages in logging system.

Parameters:

channel – if a channel is given only its messages are dumped otherwise all messages are dumped.

int sendMessage(Channel *channel, const Message &msg, pomp::Connection *conn = nullptr)#

Send a message.

Parameters:

  • channel – channel on which the message shall be sent.

  • msg – message to send.

  • conn – remote connection to target. If nullptr, and it will broadcast the message to all peers connected to the associated channel.

Returns:

0 in case of success, negative errno in case of error.

void attachMessageSender(MessageSender *msgSender, Channel *channel)#

Attach a message sender to a channel. All message sent with the given sender will go through the given channel.

Parameters:

  • msgSender – message sender to attach.

  • channel – channel to attach.

void detachMessageSender(MessageSender *msgSender)#

Detach a message sender.

Parameters:

msgSender – message sender to detach.

void attachMessageHandler(MessageHandler *msgHandler)#

Attach a message handler. Any message received on any channel with a service Id matching the one in the handler will be routed.

Remark

if the given message handler has an empty service name it will be attached as a ‘generic’ handler and will receive all messages regarding of their message Id.

Parameters:

msgHandler – message handler to attach.

void detachMessageHandler(MessageHandler *msgHandler)#

Detach a message handler.

Parameters:

msgHandler – message handler to detach.

inline const Message *getCurrentMessage() const#

During the processing of an incoming message (in any of the ‘handle’ method of an attached handler), get the current processed message.

Returns:

current processed message.

inline pomp::Connection *getCurrentMessageConnection() const#

During the processing of an incoming message (in any of the ‘handle’ method of an attached handler), get the ‘pomp’ connection object on which the message was actually received. Can be used to reply only to this connection.

Returns:

‘pomp’ connection object of the current processed message.

void forwardMessage(const Message &msg)#

Send the given message to all sender objects that have a matching service Id.

Parameters:

msg – message to send.

uint16_t getServiceId(const std::string &name)#

Get the service Id from a service name.

Parameters:

name – service name.

Returns:

service Id associated with the given service name.

class ConnectionHandler#

Interface for notification of connection/disconnection of remote peer for a given connection. It gives the underlying ‘pomp’ Connection object to access information about the peer. This Connection object can also be used to send messages to a given peer instead of broadcasting them.

Public Functions

inline ConnectionHandler()#

Constructor.

inline virtual ~ConnectionHandler()#

Destructor.

inline virtual void onConnected(Channel *channel, pomp::Connection *conn)#

Method called when a remote peer is connected.

Parameters:

  • channel – associated Channel object.

  • conn – associated ‘pomp’ Connection object.

inline virtual void onDisconnected(Channel *channel, pomp::Connection *conn)#

Method called when a remote peer is disconnected.

Parameters:

  • channel – associated Channel object.

  • conn – associated ‘pomp’ Connection object.

inline virtual void onAllClientsConnected()#

Method called when all channels created in a MessageHub object have a remote peer connected.

class Channel#

Public Functions

Channel(MessageHub *messageHub, pomp::Loop *pompLoop)#
~Channel()#
int connect(const pomp::Address &addr)#
int listen(const pomp::Address &addr, uint32_t mode = 0)#
int bind(const pomp::Address &addr)#
void stop()#
int sendMessage(const Message &msg, pomp::Connection *conn = nullptr)#
inline void enableDump()#
inline bool hasPeers()#