This is implemented as a singleton. More...

#include <uORBManager.hpp>

Public Member Functions
uORB::DeviceMaster *	get_device_master ()
	Get the DeviceMaster. More...

orb_advert_t	orb_advertise (const struct orb_metadata meta, const void data, unsigned int queue_size=1)
	Advertise as the publisher of a topic. More...

orb_advert_t	orb_advertise_multi (const struct orb_metadata meta, const void data, int *instance, int priority, unsigned int queue_size=1)
	Advertise as the publisher of a topic. More...

int	orb_unadvertise (orb_advert_t handle)
	Unadvertise a topic. More...

int	orb_publish (const struct orb_metadata meta, orb_advert_t handle, const void data)
	Publish new data to a topic. More...

int	orb_subscribe (const struct orb_metadata *meta)
	Subscribe to a topic. More...

int	orb_subscribe_multi (const struct orb_metadata *meta, unsigned instance)
	Subscribe to a multi-instance of a topic. More...

int	orb_unsubscribe (int handle)
	Unsubscribe from a topic. More...

int	orb_copy (const struct orb_metadata meta, int handle, void buffer)
	Fetch data from a topic. More...

int	orb_check (int handle, bool *updated)
	Check whether a topic has been published to since the last orb_copy. More...

int	orb_stat (int handle, uint64_t *time)
	Return the last time that the topic was updated. More...

int	orb_exists (const struct orb_metadata *meta, int instance)
	Check if a topic has already been created and published (advertised) More...

int	orb_priority (int handle, int32_t *priority)
	Return the priority of the topic. More...

int	orb_set_interval (int handle, unsigned interval)
	Set the minimum interval between which updates are seen for a subscription. More...

int	orb_get_interval (int handle, unsigned *interval)
	Get the minimum interval between which updates are seen for a subscription. More...

Static Public Member Functions
static bool	initialize ()
	Initialize the singleton. More...

static uORB::Manager *	get_instance ()
	Method to get the singleton instance for the uORB::Manager. More...

Detailed Description

This is implemented as a singleton.

This class manages creating the uORB nodes for each uORB topics and also implements the behavor of the uORB Api's.

Member Function Documentation

§ get_device_master()

uORB::DeviceMaster * uORB::Manager::get_device_master ( )

Get the DeviceMaster.

If it does not exist, it will be created and initialized. Note: the first call to this is not thread-safe.

Returns: nullptr if initialization failed (and errno will be set)

§ get_instance()

static uORB::Manager* uORB::Manager::get_instance ( )

inlinestatic

Method to get the singleton instance for the uORB::Manager.

Make sure initialize() is called first.

Returns: uORB::Manager*

§ initialize()

bool uORB::Manager::initialize ( )

static

Initialize the singleton.

Call this before everything else.

Returns: true on success

§ orb_advertise()

orb_advert_t uORB::Manager::orb_advertise	(	const struct orb_metadata *	meta,
		const void *	data,
		unsigned int	queue_size = `1`
	)

inline

Advertise as the publisher of a topic.

This performs the initial advertisement of a topic; it creates the topic node in /obj if required and publishes the initial data.

Any number of advertisers may publish to a topic; publications are atomic but co-ordination between publishers is not provided by the ORB.

Internally this will call orb_advertise_multi with an instance of 0 and default priority.

Parameters

meta	The uORB metadata (usually from the ORB_ID() macro) for the topic.
data	A pointer to the initial data to be published. For topics updated by interrupt handlers, the advertisement must be performed from non-interrupt context.
queue_size	Maximum number of buffered elements. If this is 1, no queuing is used.

Returns: nullptr on error, otherwise returns an object pointer that can be used to publish to the topic. If the topic in question is not known (due to an ORB_DEFINE with no corresponding ORB_DECLARE) this function will return nullptr and set errno to ENOENT.

§ orb_advertise_multi()

orb_advert_t uORB::Manager::orb_advertise_multi	(	const struct orb_metadata *	meta,
		const void *	data,
		int *	instance,
		int	priority,
		unsigned int	queue_size = `1`
	)

Advertise as the publisher of a topic.

This performs the initial advertisement of a topic; it creates the topic node in /obj if required and publishes the initial data.

Any number of advertisers may publish to a topic; publications are atomic but co-ordination between publishers is not provided by the ORB.

The multi can be used to create multiple independent instances of the same topic (each instance has its own buffer). This is useful for multiple publishers who publish the same topic. The subscriber then subscribes to all instances and chooses which source he wants to use.

Parameters

meta	The uORB metadata (usually from the ORB_ID() macro) for the topic.
data	A pointer to the initial data to be published. For topics updated by interrupt handlers, the advertisement must be performed from non-interrupt context.
instance	Pointer to an integer which will yield the instance ID (0-based) of the publication. This is an output parameter and will be set to the newly created instance, ie. 0 for the first advertiser, 1 for the next and so on.
priority	The priority of the instance. If a subscriber subscribes multiple instances, the priority allows the subscriber to prioritize the best data source as long as its available. The subscriber is responsible to check and handle different priorities (

See also: orb_priority()).

Parameters

queue_size Maximum number of buffered elements. If this is 1, no queuing is used.

Returns: PX4_ERROR on error, otherwise returns a handle that can be used to publish to the topic. If the topic in question is not known (due to an ORB_DEFINE with no corresponding ORB_DECLARE) this function will return -1 and set errno to ENOENT.

§ orb_check()

int uORB::Manager::orb_check	(	int	handle,
		bool *	updated
	)

Check whether a topic has been published to since the last orb_copy.

This check can be used to determine whether to copy the topic when not using poll(), or to avoid the overhead of calling poll() when the topic is likely to have updated.

Updates are tracked on a per-handle basis; this call will continue to return true until orb_copy is called using the same handle. This interface should be preferred over calling orb_stat due to the race window between stat and copy that can lead to missed updates.

Parameters

handle	A handle returned from orb_subscribe.
updated	Set to true if the topic has been updated since the last time it was copied using this handle.

Returns: OK if the check was successful, PX4_ERROR otherwise with errno set accordingly.

§ orb_copy()

int uORB::Manager::orb_copy	(	const struct orb_metadata *	meta,
		int	handle,
		void *	buffer
	)

Fetch data from a topic.

This is the only operation that will reset the internal marker that indicates that a topic has been updated for a subscriber. Once poll or check return indicating that an updaet is available, this call must be used to update the subscription.

Parameters

meta	The uORB metadata (usually from the ORB_ID() macro) for the topic.
handle	A handle returned from orb_subscribe.
buffer	Pointer to the buffer receiving the data, or NULL if the caller wants to clear the updated flag without using the data.

Returns: OK on success, PX4_ERROR otherwise with errno set accordingly.

§ orb_exists()

int uORB::Manager::orb_exists	(	const struct orb_metadata *	meta,
		int	instance
	)

Check if a topic has already been created and published (advertised)

Parameters

meta	ORB topic metadata.
instance	ORB instance

Returns: OK if the topic exists, PX4_ERROR otherwise.

§ orb_get_interval()

int uORB::Manager::orb_get_interval	(	int	handle,
		unsigned *	interval
	)

Get the minimum interval between which updates are seen for a subscription.

See also: orb_set_interval()

Parameters

handle	A handle returned from orb_subscribe.
interval	The returned interval period in milliseconds.

Returns: OK on success, PX4_ERROR otherwise with ERRNO set accordingly.

§ orb_priority()

int uORB::Manager::orb_priority	(	int	handle,
		int32_t *	priority
	)

Return the priority of the topic.

Parameters

handle	A handle returned from orb_subscribe.
priority	Returns the priority of this topic. This is only relevant for topics which are published by multiple publishers (e.g. mag0, mag1, etc.) and allows a subscriber to pick the topic with the highest priority, independent of the startup order of the associated publishers.

Returns: OK on success, PX4_ERROR otherwise with errno set accordingly.

§ orb_publish()

int uORB::Manager::orb_publish	(	const struct orb_metadata *	meta,
		orb_advert_t	handle,
		const void *	data
	)

Publish new data to a topic.

The data is atomically published to the topic and any waiting subscribers will be notified. Subscribers that are not waiting can check the topic for updates using orb_check and/or orb_stat.

Parameters

meta	The uORB metadata (usually from the ORB_ID() macro) for the topic. The handle returned from orb_advertise.
data	A pointer to the data to be published.

Returns: OK on success, PX4_ERROR otherwise with errno set accordingly.

§ orb_set_interval()

int uORB::Manager::orb_set_interval	(	int	handle,
		unsigned	interval
	)

Set the minimum interval between which updates are seen for a subscription.

If this interval is set, the subscriber will not see more than one update within the period.

Specifically, the first time an update is reported to the subscriber a timer is started. The update will continue to be reported via poll and orb_check, but once fetched via orb_copy another update will not be reported until the timer expires.

This feature can be used to pace a subscriber that is watching a topic that would otherwise update too quickly.

Parameters

handle	A handle returned from orb_subscribe.
interval	An interval period in milliseconds.

Returns: OK on success, PX4_ERROR otherwise with ERRNO set accordingly.

§ orb_stat()

int uORB::Manager::orb_stat	(	int	handle,
		uint64_t *	time
	)

Return the last time that the topic was updated.

If a queue is used, it returns the timestamp of the latest element in the queue.

Parameters

handle	A handle returned from orb_subscribe.
time	Returns the absolute time that the topic was updated, or zero if it has never been updated. Time is measured in microseconds.

Returns: OK on success, PX4_ERROR otherwise with errno set accordingly.

§ orb_subscribe()

int uORB::Manager::orb_subscribe ( const struct orb_metadata * meta )

Subscribe to a topic.

The returned value is a file descriptor that can be passed to poll() in order to wait for updates to a topic, as well as topic_read, orb_check and orb_stat.

If there were any publications of the topic prior to the subscription, an orb_check right after orb_subscribe will return true.

Subscription will succeed even if the topic has not been advertised; in this case the topic will have a timestamp of zero, it will never signal a poll() event, checking will always return false and it cannot be copied. When the topic is subsequently advertised, poll, check, stat and copy calls will react to the initial publication that is performed as part of the advertisement.

Subscription will fail if the topic is not known to the system, i.e. there is nothing in the system that has declared the topic and thus it can never be published.

Internally this will call orb_subscribe_multi with instance 0.

Parameters

meta	The uORB metadata (usually from the ORB_ID() macro) for the topic.

Returns: PX4_ERROR on error, otherwise returns a handle that can be used to read and update the topic.

§ orb_subscribe_multi()

int uORB::Manager::orb_subscribe_multi	(	const struct orb_metadata *	meta,
		unsigned	instance
	)

Subscribe to a multi-instance of a topic.

The returned value is a file descriptor that can be passed to poll() in order to wait for updates to a topic, as well as topic_read, orb_check and orb_stat.

If there were any publications of the topic prior to the subscription, an orb_check right after orb_subscribe_multi will return true.

Subscription will succeed even if the topic has not been advertised; in this case the topic will have a timestamp of zero, it will never signal a poll() event, checking will always return false and it cannot be copied. When the topic is subsequently advertised, poll, check, stat and copy calls will react to the initial publication that is performed as part of the advertisement.

Subscription will fail if the topic is not known to the system, i.e. there is nothing in the system that has declared the topic and thus it can never be published.

If a publisher publishes multiple instances the subscriber should subscribe to each instance with orb_subscribe_multi (

See also: orb_advertise_multi()).

Parameters

meta	The uORB metadata (usually from the ORB_ID() macro) for the topic.
instance	The instance of the topic. Instance 0 matches the topic of the orb_subscribe() call, higher indices are for topics created with orb_advertise_multi().

Returns: PX4_ERROR on error, otherwise returns a handle that can be used to read and update the topic. If the topic in question is not known (due to an ORB_DEFINE_OPTIONAL with no corresponding ORB_DECLARE) this function will return -1 and set errno to ENOENT.

§ orb_unadvertise()

int uORB::Manager::orb_unadvertise ( orb_advert_t handle )

Unadvertise a topic.

Parameters

handle handle returned by orb_advertise or orb_advertise_multi.

Returns: 0 on success

§ orb_unsubscribe()

int uORB::Manager::orb_unsubscribe ( int handle )

Unsubscribe from a topic.

Parameters

handle A handle returned from orb_subscribe.

Returns: OK on success, PX4_ERROR otherwise with errno set accordingly.

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

src/modules/uORB/uORBManager.hpp
src/modules/uORB/uORBManager.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

§ get_device_master()

§ get_instance()

§ initialize()

§ orb_advertise()

§ orb_advertise_multi()

§ orb_check()

§ orb_copy()

§ orb_exists()

§ orb_get_interval()

§ orb_priority()

§ orb_publish()

§ orb_set_interval()

§ orb_stat()

§ orb_subscribe()

§ orb_subscribe_multi()

§ orb_unadvertise()

§ orb_unsubscribe()