Feature/j2735 geofence convertor (usdot-fhwa-stol#54)

* Add more detailed comments describing how to use a geofence schedule * Remove invalid optional indicators from geofence message
xuhan417 · May 7, 2020 · 349ae08 · 349ae08
1 parent 37bc3dc
commit 349ae08
Show file tree

Hide file tree

Showing 6 changed files with 55 additions and 46 deletions.
diff --git a/cav_msgs/msg/ControlMessage.msg b/cav_msgs/msg/ControlMessage.msg
@@ -1,9 +1,7 @@
 #
 # ControlMessage.msg
 #
-# Part of the CARMA Cloud geo-fence specification not part of the official SAE j2735 standard
-#
-# J2735 2016 message format.
+# Part of the CARMA Cloud geo-fence specification for vehicle internal use.
 #
 # @author Misheel Bayartsengel 
 # @version 0.1
@@ -63,18 +61,12 @@ float64 latitude
 # Altitude in meters
 # -- In units of 0.1m steps above the sea level
 # -- Providing a range of 0 to + 9276.0 meters
-# -- The altitude_available boolean shall be set false when Unknown is to be sent
 float32 altitude
 
-bool altitude_available
-
 # Heading in degrees
 # -- In units of 0.1 deg steps
 # -- A range of 0 to 359.9 degrees
-# -- The heading_available boolean shall be set false when heading is unavailable
 float32 heading
 
-bool heading_available
-
 # Points ::= SEQUENCE (SIZE(2..100)) OF Point
 cav_msgs/Point[] points
diff --git a/cav_msgs/msg/DaySchedule.msg b/cav_msgs/msg/DaySchedule.msg
@@ -1,27 +1,28 @@
 #
 # DaySchedule.msg
 #
-# Part of the CARMA Cloud geo-fence specification not part of the official SAE j2735 standard
-#
-# J2735 2016 message format.
+# Part of the CARMA Cloud geo-fence specification for vehicle internal use.
 #
 # @author Misheel Bayartsengel 
 # @version 0.1
 #
 # Description
-# ...
+# The schedule bounds of a geofence within a specific day of the week and the UTC timezone (as an offset) of the day of the week. 
 
 # Start 
-# -- offset seconds of the day (0..86399)
+# Specifies the start of time of the schedule.
+# If a ScheduleParams are not specified than this geofence is immediately active once this start time is exceeded on a given day. 
+# If the ScheduleParams are specified than the start time simply bounds the activation periods.
+# Start time cannot exceed midnight.
 duration start
 
 # End 
-# -- offset seconds of the day (0..86399)
+# Activation bound for this geofence. Once this point is exceeded the geofence cannot be active.
+# Ent time cannot exceed midnight or be less than start time.
 duration end
 
 # UTCOffset 
-# -- time offset of UTC in seconds (-43200 .. 50400)
-# -- westernmost: 43200 (-12:00) to the easternmost: 50400 (14:00)
+# Defines the timezone as a UTC offset to be used for determining the day of the week.
 duration utcoffset
 
 
diff --git a/cav_msgs/msg/Schedule.msg b/cav_msgs/msg/Schedule.msg
@@ -1,38 +1,56 @@
 #
 # Schedule.msg
 #
-# Part of the CARMA Cloud geo-fence specification not part of the official SAE j2735 standard
-#
-# J2735 2016 message format.
+# Part of the CARMA Cloud geo-fence specification for vehicle internal use.
 #
 # @author Misheel Bayartsengel
 # @version 0.1
 #
 # The schedule tag supplies time-based parameters to controls. This enables temporary 
 # controls to expire and cyclic controls to repeat. A schedule has an overall start and 
-# end date and time that can be an empty string indicating forever or at least until 
-# overridden when updated. Schedules optionally specify days of the week, hours of day, 
-# and a repeat interval and duration along with the repeat unit of measure such as minutes or hours.
+# end date and tim. Schedules optionally specify days of the week, hours of day, 
+# and a repeat interval and duration.
+#
+# If a geofence needs to be active through midnight than the DayOfWeek and DaySchedule cannot be used and the start, end, and ScheduleParams should be used instead.
 
-# Start Time in seconds
-# -- time when this schedule starts
+# Start Time in UTC seconds
+# Specifies the start of time of the schedule
+# If a DayOfWeek is not specified than the geofence is immediately active once past this start time.
+# If the DayOfWeek is specified than the start time simply bounds the activation periods.
 time start
 
-# End Time in seconds
-# -- time when this schedule ends
+# End Time in UTC seconds
+# Specifies the end of time of the schedule
+# Past this end time a geofence is never active
 time end
 
 # DayOfWeek OPTIONAL ::= SEQUENCE (SIZE(7)) OF BOOLEAN
+# Specifies the days of the week where this geofence will be active.
 # -- 0=sunday, 1=monday, ...
 # -- if monday, dow = [false, true, false, false, false, false, false]
+# If this is set than the DaySchedule must also be set.
 bool[7] dow
 bool dow_exists
 
-# between DaySchedule OPTIONAL
+# Enum for accessing dow index
+uint8 SUN=0
+uint8 MON=1
+uint8 TUES=2
+uint8 WED=3
+uint8 THUR=4
+uint8 FRI=5
+uint8 SAT=6
+
+# DaySchedule OPTIONAL
+# A day schedule defines when the geofence will be active during the day.
+# If this is set then the day of the week (dow) must also be specified.
+# The time specified by the DaySchedule cannot cross midnight. 
 cav_msgs/DaySchedule between
 bool between_exists
 
-# repeat ScheduleParams OPTIONAL
+# ScheduleParams OPTIONAL
+# The schedule parameters define the duration and repetition of the geofence activation
+# If a DayOfWeek is specified than the duration+interval must not exceed 24hrs. 
 cav_msgs/ScheduleParams repeat
 bool repeat_exists
 
diff --git a/cav_msgs/msg/ScheduleParams.msg b/cav_msgs/msg/ScheduleParams.msg
@@ -1,20 +1,24 @@
 #
 # ScheduleParams.msg
 #
-# Part of the CARMA Cloud geo-fence specification not part of the official SAE j2735 standard
-#
-# J2735 2016 message format.
+# Part of the CARMA Cloud geo-fence specification for vehicle internal use.
 #
 # @author Misheel Bayartsengel
 # @version 0.1
 #
 # Description
-# ...
+# Message describing a geofence activation period and repeating interval.
+# Once a geofence becomes active it will remain active for the specified duration.
+# Once the duration as elapsed the geofence will become inactive until the specified interval has elapsed from the 
+# previous duration START time. 
+# So if you have an interval of 30m and duration of 15m,
+# then starting at t=0 you will have activation from 0-15m and 30-45m. 
 
 # Interval
-#  -- duration between start times in seconds (min: 0)
+# The interval between repeats of geofence activation.
 duration interval
 
-# Duration ::= INTEGER
-# -- duration of schedule in minutes, must be less than interval (min :0)
+# Duration
+# The duration which a geofence will remain active for. 
+# This must not exceed the specified interval.
 duration duration
diff --git a/j2735_msgs/msg/ControlBounds.msg b/j2735_msgs/msg/ControlBounds.msg
@@ -23,25 +23,23 @@
 # -- A UNIX timestamp in milliseconds, which indicates the time elapsed since UNIX epoch
 uint64 oldest
 
-# Longitude ::= INTEGER (-1799999999..1800000001)
+# Longitude ::= INTEGER (-1799999999..1800000000)
 # -- initial vertex reference longitude
 # -- LSB = 1/10 micro degree
 # -- Providing a range of plus-minus 180 degrees
 # -- Convert to degree with factor 0.0000001 when field is used
 int32 longitude
 
-int32 LONGITUDE_UNAVAILABLE = 1800000001
 int32 LONGITUDE_MAX = 1800000000
 int32 LONGITUDE_MIN = -1799999999
 
-# Latitude ::= INTEGER (-900000000..900000001)
+# Latitude ::= INTEGER (-900000000..900000000)
 # -- initial vertex reference latitude
 # -- LSB = 1/10 micro degree
 # -- Providing a range of plus-minus 90 degrees
 # -- Convert to degree with factor 0.0000001 when field is used
 int32 latitude
 
-int32 LATITUDE_UNAVAILABLE = 900000001
 int32 LATITUDE_MAX = 900000000
 int32 LATITUDE_MIN = -900000000
 

diff --git a/j2735_msgs/msg/ControlMessage.msg b/j2735_msgs/msg/ControlMessage.msg
@@ -77,23 +77,21 @@ string datum
 # -- A UNIX timestamp in milliseconds, which indicates the time elapsed since UNIX epoch
 uint64 time
 
-# Longitude ::= INTEGER (-1799999999..1800000001)
+# Longitude ::= INTEGER (-1799999999..1800000000)
 # -- LSB = 1/10 micro degree
 # -- Providing a range of plus-minus 180 degrees
 # -- Convert to degree with factor 0.0000001 when field is used
 int32 longitude
 
-int32 LONGITUDE_UNAVAILABLE = 1800000001
 int32 LONGITUDE_MAX = 1800000000
 int32 LONGITUDE_MIN = -1799999999
 
-# Latitude ::= INTEGER (-900000000..900000001)
+# Latitude ::= INTEGER (-900000000..900000000)
 # -- LSB = 1/10 micro degree
 # -- Providing a range of plus-minus 90 degrees
 # -- Convert to degree with factor 0.0000001 when field is used
 int32 latitude
 
-int32 LATITUDE_UNAVAILABLE = 900000001
 int32 LATITUDE_MAX = 900000000
 int32 LATITUDE_MIN = -900000000
 
@@ -105,7 +103,6 @@ int32 LATITUDE_MIN = -900000000
 # -- Convert to meter with factor 0.1 when field is used
 uint32 altitude
 
-uint32 ALTITUDE_UNAVAILABLE = 92761
 uint32 ALTITUDE_MAX = 92760
 
 # Heading ::= INTEGER (0..3599)
@@ -114,7 +111,6 @@ uint32 ALTITUDE_MAX = 92760
 # -- A range of 0 to 359.9 degrees
 # -- Convert to degree with factor 0.1 when field is used
 uint16 heading
-uint16 HEADING_UNAVAILABLE = 3600
 uint16 HEADING_MAX = 3599
 uint16 HEADING_MIN = 0