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.
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
-
MessageSender(const std::string &serviceName)#
-
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.
-
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.
-
inline ConnectionHandler()#
-
MessageHub(pomp::Loop *pompLoop, ConnectionHandler *connectionHandler)#
-
class Channel#