From 4a445178c38c89b4f91cd84d3be261d7fe5ca47f Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Mon, 24 Aug 2020 16:46:53 -0700 Subject: [PATCH 1/2] Document TimeSource class Signed-off-by: Jacob Perron --- .../org/ros2/rcljava/time/TimeSource.java | 57 +++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/rcljava/src/main/java/org/ros2/rcljava/time/TimeSource.java b/rcljava/src/main/java/org/ros2/rcljava/time/TimeSource.java index 44318c2d..0999ee7c 100644 --- a/rcljava/src/main/java/org/ros2/rcljava/time/TimeSource.java +++ b/rcljava/src/main/java/org/ros2/rcljava/time/TimeSource.java @@ -33,6 +33,15 @@ import java.util.concurrent.LinkedBlockingQueue; +/** + * Implementation of the ROS time source abstraction. + * + * The abstraction uses a subscription to a "/clock" topic as described in + * the design document + * Clock and Time. + * + * A @{link Node} needs to be attached to a TimeSource in order for subscription to be created. + */ public final class TimeSource { private Node node; private boolean rosTimeIsActive; @@ -43,10 +52,18 @@ public final class TimeSource { private static final Logger logger = LoggerFactory.getLogger(TimeSource.class); + /** + * Empty constructor. + */ public TimeSource() { this(null); } + /** + * Attach a node to the time source. + * + * @param node The node to attach to the time source. + */ public TimeSource(Node node) { this.rosTimeIsActive = false; this.associatedClocks = new LinkedBlockingQueue(); @@ -57,6 +74,10 @@ public TimeSource(Node node) { } } + /** + * @return true if ROS time is active, false otherwise. + * Being active means we are listening to the "/clock" topic. + */ public boolean getRosTimeIsActive() { return this.rosTimeIsActive; } @@ -77,6 +98,11 @@ public void accept(final rosgraph_msgs.msg.Clock msg) { } } + /** + * Enable or disable ROS time. + * + * @param enabled Flag to enable or disable ROS time. + */ public void setRosTimeIsActive(boolean enabled) { if (this.rosTimeIsActive == enabled) { return; @@ -97,6 +123,14 @@ public void setRosTimeIsActive(boolean enabled) { } } + /** + * Attach a @{link Node} to the time source. + * + * This node is used to create a subscription to the "/clock" topic. + * Any previously attached @{link Node} is detached. + * + * @param node The node to attach to the time source. + */ public void attachNode(Node node) { if (this.node != null) { detachNode(); @@ -148,6 +182,13 @@ public rcl_interfaces.msg.SetParametersResult callback(List pa this.node.addOnSetParametersCallback(this.simTimeCB); } + /** + * Detach a @{link Node} from the time source. + * + * Unsubscribes from the "/clock" topic, effectively disabling ROS time. + * + * If no Node is attached, nothing happens. + */ public void detachNode() { if (this.node == null) { return; @@ -157,6 +198,15 @@ public void detachNode() { this.node = null; } + /** + * Attach a @{link Clock} to the time source. + * + * More than one clock may be attached to a time source. + * Attached clocks will be updated to the the time received on the "/clock" topic. + * + * @param clock The Clock to attach. + * Must be of type @{link ClockType.ROS_TIME}, otherwise an exception is thrown. + */ public void attachClock(Clock clock) { if (clock.getClockType() != ClockType.ROS_TIME) { // TODO(clalancette): Make this a custom exception @@ -167,6 +217,13 @@ public void attachClock(Clock clock) { this.associatedClocks.add(clock); } + /** + * Detach a @{link Clock} from the time source. + * + * The Clock will no longer receive time updates from this time source. + * + * @param clock The Clock to detach. + */ public void detachClock(Clock clock) { this.associatedClocks.remove(clock); } From 2907d29311f56a4ae66a03650ba840b22c7996e4 Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Tue, 25 Aug 2020 09:37:24 -0700 Subject: [PATCH 2/2] Address feedback * Empty -> Default * Add more detail to class docblock Signed-off-by: Jacob Perron --- .../java/org/ros2/rcljava/time/TimeSource.java | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/rcljava/src/main/java/org/ros2/rcljava/time/TimeSource.java b/rcljava/src/main/java/org/ros2/rcljava/time/TimeSource.java index 0999ee7c..27e4bbc2 100644 --- a/rcljava/src/main/java/org/ros2/rcljava/time/TimeSource.java +++ b/rcljava/src/main/java/org/ros2/rcljava/time/TimeSource.java @@ -36,11 +36,17 @@ /** * Implementation of the ROS time source abstraction. * - * The abstraction uses a subscription to a "/clock" topic as described in - * the design document - * Clock and Time. + * This class updates the time of one or more @{link Clock}s with a ROS time source. + * A ROS time source is expected to be published to the "/clock" topic. + * A TimeSource object needs a @{link Node} in order create a subscription to the "/clock" topic. + * + * There are two ways to enable (or disable) using a ROS time source: * - * A @{link Node} needs to be attached to a TimeSource in order for subscription to be created. + * 1. Calling the method @{link #setRosTimeIsActive(boolean)}, or + * 2. Setting the 'use_sim_time' parameter on the @{link Node} that is attached to this TimeSource + * + * More information can be found in the design document + * Clock and Time. */ public final class TimeSource { private Node node; @@ -53,7 +59,7 @@ public final class TimeSource { private static final Logger logger = LoggerFactory.getLogger(TimeSource.class); /** - * Empty constructor. + * Default constructor. */ public TimeSource() { this(null);