Welcome to diagnostic_updater documentation!

Indices and tables

• Index
• Module Index
• Search Page

Module diagnostic_updater

diagnostic_updater contains assorted Python classes to assist in diagnostic publication. These libraries are commonly used by device drivers as part of the diagnostics toolchain. The main parts of diagnostic_updater are:

• DiagnosticStatusWrapper, a wrapper providing convenience functions for working with diagnostics_msgs/DiagnosticStatus.
• Updater, a class for managing periodic publishing of the DiagnosticStatusWrapper output by a set of DiagnosticTask.
• TopicDiagnostic and HeaderlessTopicDiagnostic for calculating and publishing statistics on timestamps and publication frequencies, and their corresponding DiagnosedPublisher and HeaderlessDiagnosedPublisher to update the statistics automatically when publications are made to a topic.

Example uses of these classes can be found in src/example.py.

class diagnostic_updater.DiagnosticStatusWrapper(*args, **kwds)

Bases: diagnostic_msgs/DiagnosticStatus

Wrapper for the diagnostic_msgs/DiagnosticStatus message that makes it easier to update.

This class handles common string formatting and vector handling issues for filling the diagnostic_msgs/DiagnosticStatus message. It is a subclass of diagnostic_msgs/DiagnosticStatus, so it can be passed directly to diagnostic publish calls.

Constructor. Any message fields that are implicitly/explicitly set to None will be assigned a default value. The recommend use is keyword arguments as this is more robust to future message changes. You cannot mix in-order arguments and keyword arguments.

The available fields are: level,name,message,hardware_id,values

Parameters:

• args – complete set of field values, in .msg order
• kwds – use keyword arguments corresponding to message field names to set specific fields.

add(key, val)

Add a key-value pair.

This method adds a key-value pair.

Parameters:

• key (string) – Key to be added.
• value – Value to be added.

clearSummary()

Clears the summary, setting the level to zero and the message to “”.

mergeSummary(*args)

Merges a level and message with the existing ones.

It is sometimes useful to merge two diagnostic_msgs/DiagnosticStatus messages. In that case, the key value pairs can be unioned, but the level and summary message have to be merged more intelligently. This function does the merge in an intelligent manner, combining the summary in this, with the one that is passed in.

The combined level is the greater of the two levels to be merged. If both levels are non-zero (not OK), the messages are combined with a semicolon separator. If only one level is zero, and the other is non-zero, the message for the zero level is discarded. If both are zero, the new message is ignored.

Usage:

mergeSummary(diagnostic_status): merge from a diagnostic_msgs/DiagnosticStatus message

mergeSummary(lvl,msg): sets from lvl and msg

summary(*args)

Fills out the level and message fields of the diagnostic_msgs/DiagnosticStatus.

Usage:

summary(diagnostic_status): Copies the summary from a diagnostic_msgs/DiagnosticStatus message

summary(lvl,msg): sets from lvl and messages

class diagnostic_updater.DiagnosticTask(name)

Bases: object

DiagnosticTask is an abstract base class for collecting diagnostic data.

Subclasses are provided for generating common diagnostic information. A DiagnosticTask has a name, and a function that is called to create a DiagnosticStatusWrapper.

Constructs a DiagnosticTask setting its name in the process.

Parameters:name (str) – The name of the diagnostic task.

getName()

Returns the name of the DiagnosticTask.

Return type:str

run(stat)

Fills out this Task’s DiagnosticStatusWrapper.

Parameters:stat (DiagnosticStatusWrapper) – the DiagnosticStatusWrapper to fill Returns:the filled DiagnosticStatusWrapper Return type:DiagnosticStatusWrapper

class diagnostic_updater.FunctionDiagnosticTask(name, fn)

Bases: diagnostic_updater._diagnostic_updater.DiagnosticTask

A DiagnosticTask based on a function.

The FunctionDiagnosticTask calls the function when it updates. The function updates the DiagnosticStatusWrapper and collects data.

This is useful for gathering information about a device or driver, like temperature, calibration, etc.

Constructs a GenericFunctionDiagnosticTask based on the given name and function.

Parameters:

• name (str) – Name of the function.
• fn – Function to be called when run is called.

run(stat)

Fills out this Task’s DiagnosticStatusWrapper.

Parameters:stat (DiagnosticStatusWrapper) – the DiagnosticStatusWrapper to fill Returns:the filled DiagnosticStatusWrapper Return type:DiagnosticStatusWrapper

class diagnostic_updater.CompositeDiagnosticTask(name)

Bases: diagnostic_updater._diagnostic_updater.DiagnosticTask

Merges CompositeDiagnosticTask into a single DiagnosticTask.

The CompositeDiagnosticTask allows multiple DiagnosticTask instances to be combined into a single task that produces a single DiagnosticStatusWrapper. The output of the combination has the max of the status levels, and a concatenation of the non-zero-level messages.

For instance, this could be used to combine the calibration and offset data from an IMU driver.

Variables:tasks (list of DiagnosticTask) – List of tasks

Constructs a CompositeDiagnosticTask with the given name.

Parameters:name (str) – The name of the diagnostic task.

addTask(t)

Adds a child CompositeDiagnosticTask.

This CompositeDiagnosticTask will be called each time this CompositeDiagnosticTask is run.

Parameters:t (DiagnosticTask) – the DiagnosticTask to add.

run(stat)

Fills out this Task’s DiagnosticStatusWrapper.

Parameters:stat (DiagnosticStatusWrapper) – the DiagnosticStatusWrapper to fill Returns:the filled DiagnosticStatusWrapper Return type:DiagnosticStatusWrapper

class diagnostic_updater.DiagnosticTaskVector

Bases: object

Internal use only.

Base class for Updater and self_test::Dispatcher. The class manages a collection of diagnostic updaters. It contains the common functionality used for producing diagnostic updates and for self-tests.

Variables:

• tasks (list of DiagnosticTask) – List of tasks
• lock (threading.Lock) – The lock protecting the enclosed list of tasks.

class DiagnosticTaskInternal(name, fn)

Bases: object

Class used to represent a diagnostic task internally in DiagnosticTaskVector.

run(stat)

add(*args)

Add a task to the DiagnosticTaskVector.

Usage:

add(task): where task is a DiagnosticTask

add(name, fn): add a DiagnosticTask embodied by a name and function

addedTaskCallback(task)

Allows an action to be taken when a task is added. The Updater class uses this to immediately publish a diagnostic that says that the node is loading.

Parameters:task (DiagnosticTask) – the added task.

removeByName(name)

Removes a task based on its name.

Removes the first task that matches the specified name. (New in version 1.1.2)

Parameters:name (str) – Name of the task to remove. Returns:Returns true if a task matched and was removed. Return type:bool

class diagnostic_updater.Updater

Bases: diagnostic_updater._diagnostic_updater.DiagnosticTaskVector

Manages a list of diagnostic tasks, and calls them in a rate-limited manner.

This class manages a list of diagnostic tasks. Its update function should be called frequently. At some predetermined rate, the update function will cause all the diagnostic tasks to run, and will collate and publish the resulting diagnostics. The publication rate is determined by the ~diagnostic_period ros parameter.

The class also allows an update to be forced when something significant has happened, and allows a single message to be broadcast on all the diagnostics if normal operation of the node is suspended for some reason.

Constructs an updater class.

addedTaskCallback(task)

Allows an action to be taken when a task is added. The Updater class uses this to immediately publish a diagnostic that says that the node is loading.

Parameters:task (DiagnosticTask) – the added task.

broadcast(lvl, msg)

Outputs a message on all the known DiagnosticStatus.

Useful if something drastic is happening such as shutdown or a self-test.

Parameters:

• lvl (int) – Level of the diagnostic being output.
• msg (str) – Status message to output.

force_update()

Forces the diagnostics to update.

Useful if the node has undergone a drastic state change that should be published immediately.

publish(msg)

Publishes a single diagnostic status or a vector of diagnostic statuses.

Parameters:msg (diagnostic_msgs/DiagnosticStatus) – The status(es) to publish.

setHardwareID(hwid)

Parameters:hwid (str) – The hardware ID.

update()

Causes the diagnostics to update if the inter-update interval has been exceeded.

class diagnostic_updater.HeaderlessTopicDiagnostic(name, diag, freq)

Bases: diagnostic_updater._diagnostic_updater.CompositeDiagnosticTask

A class to facilitate making diagnostics for a topic using a FrequencyStatus.

The word “headerless” in the class name refers to the fact that it is mainly designed for use with messages that do not have a header, and that cannot therefore be checked using a TimeStampStatus.

Constructs a HeaderlessTopicDiagnostic.

Parameters:

• name (str) – The name of the topic that is being diagnosed.
• diag (diagnostic_updater.Updater) – The Updater that the CompositeDiagnosticTask should add itself to.
• freq (diagnostic_updater.FrequencyStatusParam) – The parameters for the FrequencyStatus class that will be computing statistics.

clear_window()

Clears the frequency statistics.

tick()

Signals that a publication has occurred.

class diagnostic_updater.TopicDiagnostic(name, diag, freq, stamp)

Bases: diagnostic_updater._publisher.HeaderlessTopicDiagnostic

A class to facilitate making diagnostics for a topic using a FrequencyStatus and TimeStampStatus.

Constructs a TopicDiagnostic.

Parameters:

• name (str) – The name of the topic that is being diagnosed.
• diag (diagnostic_updater.Updater) – The Updater that the CompositeDiagnosticTask should add itself to.
• freq (diagnostic_updater.FrequencyStatusParam) – The parameters for the FrequencyStatus class that will be computing statistics.
• stamp (diagnostic_updater.TimeStampStatusParam) – The parameters for the TimeStampStatus class that will be computing statistics.

tick(stamp)

Collects statistics and publishes the message.

Parameters:stamp (float or rospy.Time) – Timestamp to use for interval computation by the TimeStampStatus class.

class diagnostic_updater.DiagnosedPublisher(pub, diag, freq, stamp)

Bases: diagnostic_updater._publisher.TopicDiagnostic

A TopicDiagnostic combined with a rospy.Publisher.

For a standard rospy.Publisher, this class allows the rospy.Publisher and the TopicDiagnostic to be combined for added convenience.

Constructs a DiagnosedPublisher.

Parameters:

• pub (rospy.Publisher) – The publisher on which statistics are being collected.
• diag (diagnostic_updater.Updater) – The Updater that the CompositeDiagnosticTask should add itself to.
• freq (diagnostic_updater.FrequencyStatusParam) – The parameters for the FrequencyStatus class that will be computing statistics.
• stamp (diagnostic_updater.TimeStampStatusParam) – The parameters for the TimeStampStatus class that will be computing statistics.

publish(message)

Collects statistics and publishes the message.

The timestamp to be used by the TimeStampStatus class will be extracted from message.header.stamp.

Parameters:message (genpy.Message) – The message to be published.

class diagnostic_updater.FrequencyStatusParam(freq_bound, tolerance=0.1, window_size=5)

Bases: object

A structure that holds the constructor parameters for the FrequencyStatus class.

Implementation note: the min_freq and max_freq parameters in the C++ code are stored as pointers, so that if they are updated, the new values are used. To emulate this behavior, we here use a dictionary to hold them: {‘min’,’max’}

Variables:

• freq_bound (dict) – Dictionary with keys min and max, containing the min and max acceptable frequencies.
• tolerance (float) – The tolerance with which bounds must be satisfied. Acceptable values are from freq_bound[‘min’] * (1 - torelance) to freq_bound[‘max’] * (1 + tolerance). Common use cases are to set tolerance to zero, or to assign the same value to freq_bound[‘min’] and freq_bound[‘max’].
• window_size (int) – The number of events to consider in the statistics.

Creates a filled-out FrequencyStatusParam.

Parameters:

• freq_bound (dict) – Dictionary with keys min and max, containing the min and max acceptable frequencies.
• tolerance (float) – The tolerance with which bounds must be satisfied. Acceptable values are from freq_bound[‘min’] * (1 - torelance) to freq_bound[‘max’] * (1 + tolerance). Common use cases are to set tolerance to zero, or to assign the same value to freq_bound[‘min’] and freq_bound[‘max’].
• window_size (int) – The number of events to consider in the statistics.

class diagnostic_updater.FrequencyStatus(params, name='FrequencyStatus')

Bases: diagnostic_updater._diagnostic_updater.DiagnosticTask

A diagnostic task that monitors the frequency of an event.

This diagnostic task monitors the frequency of calls to its tick method, and creates corresponding diagnostics. It will report a warning if the frequency is outside acceptable bounds, and report an error if there have been no events in the latest window.

Constructs a FrequencyStatus class with the given parameters.

Parameters:

• params (FrequencyStatus) – parameters of the diagnostic task.
• name (str) – name of the diagnostic task.

clear()

Resets the statistics.

run(stat)

Fills out this Task’s DiagnosticStatusWrapper.

Parameters:stat (DiagnosticStatusWrapper) – the DiagnosticStatusWrapper to fill Returns:the filled DiagnosticStatusWrapper Return type:DiagnosticStatusWrapper

tick()

Signals that an event has occurred.

class diagnostic_updater.TimeStampStatusParam(min_acceptable=-1, max_acceptable=5)

Bases: object

A structure that holds the constructor parameters for the TimeStampStatus class.

Variables:

• max_acceptable (float) – maximum acceptable difference between two timestamps.
• min_acceptable (float) – minimum acceptable difference between two timestamps.

Creates a filled-out TimeStampStatusParam.

Parameters:

• min_acceptable (float) – minimum acceptable difference between two timestamps.
• max_acceptable (float) – maximum acceptable difference between two timestamps.

class diagnostic_updater.TimeStampStatus(params=<diagnostic_updater._update_functions.TimeStampStatusParam object>, name='Timestamp Status')

Bases: diagnostic_updater._diagnostic_updater.DiagnosticTask

Diagnostic task to monitor the interval between events.

This diagnostic task monitors the difference between consecutive events, and creates corresponding diagnostics. An error occurs if the interval between consecutive events is too large or too small. An error condition will only be reported during a single diagnostic report unless it persists. Tallies of errors are also maintained to keep track of errors in a more persistent way.

Constructs the TimeStampStatus with the given parameters.

Parameters:

• params (TimeStampStatus) – parameters of the diagnostic task.
• name (str) – name of the diagnostic task.

run(stat)

Fills out this Task’s DiagnosticStatusWrapper.

Parameters:stat (DiagnosticStatusWrapper) – the DiagnosticStatusWrapper to fill Returns:the filled DiagnosticStatusWrapper Return type:DiagnosticStatusWrapper

tick(stamp)

Signals an event.

Parameters:stamp (float or rospy.Time.) – The timestamp of the event that will be used in computing intervals.

class diagnostic_updater.Heartbeat

Bases: diagnostic_updater._diagnostic_updater.DiagnosticTask

Diagnostic task to monitor whether a node is alive

This diagnostic task always reports as OK and ‘Alive’ when it runs

Constructs a HeartBeat

run(stat)

Fills out this Task’s DiagnosticStatusWrapper.

Parameters:stat (DiagnosticStatusWrapper) – the DiagnosticStatusWrapper to fill Returns:the filled DiagnosticStatusWrapper Return type:DiagnosticStatusWrapper