Symbolic Names for Rooms - How to Update the Knowledge Base

Specify symbolic names for locations, get coordinates of locations from a map, store symbolic names for locations in a knowledge base. Symbolic names for locations are used by navigation tasks and skills.

In the previous tutorial Map a New Environment by Driving Around with a Joystick or via Keyboard, we have created the map of the environment. This map is used for navigation and we can command the robot to move to a pose (i.e. x, y, heading). It is more efficient to use symbolic names for locations than using the coordinates directly to command the robot. For example, to move the robot in front of the refrigerator, the command (approachLocation refrigerator) is more readable than (approachLocation 6000mm, 3500mm, 1.570rad).

This tutorial explains how to specify a symbolic name for a location, how to get the coordinates of a location from a map and how to store symbolic names for locations in the knowledge base.

You also get first and very basic information about behavior models. Detailed explanations on behavior models and behavior projects (how to model tasks using the skills provided by components) are given in «to be added».

A system project can have a behavior model which will be loaded and executed upon starting the system execution. Behavior models are written in SmartTCL (Task Coordination Language). SmartTCL is a domain specific language for modeling task plots.

ComponentKB (Knowledge Base) is an utility component which provides storage/retrieval for entities described by key-value pairs. In the behavior model, one can add / update entities using tcl-kb-update and query for information from knowledge base using tcl-kb-query.

For example, the system SystemWebotsP3dxNavigation comprises the navigation behavior provided by the behavior project BehaviorNavigationTHUScenario. BehaviorNavigationTHUScenario uses the skills provided by the navigation components to drive the robot to a known given location.

You can have a look at the BehaviorNavigationTHUScenario project. You can explore the behavior projects via the behavior view in the SmartMDSD toolchain.

We specify the symbolic names of the locations in the file BehaviorNavigationTHUScenario.smartTcl.

Below figure shows the environment for which we built the map. For illustration purposes, we overlay the 2D grid map (the black dots show occupied cells of the 2D grid map, see the walls) with the coordinate system of the environment (yellow grid with a resolution of 1000mm x 1000mm with the axes in red, green, blue).

A pose (x, y, heading) [mm, mm, deg] is just a (x, y) position with an orientation. If we want to drive the robot in front of the refrigerator such that it faces to the refrigerator, we can select the pose (6100, 3500, 90). We represent the orientation via a (x, y) [mm, mm] point toward which the robot is looking. In this example, we specify the orientation by the point (6100, 5000).

Once we have identified the coordinates of poses (such as the pose for approaching the refrigerator), we create for each such pose a description. These descriptions are added to that behavior model that is used in the system project.

In the example we use here, our system comprises the behavior project BehaviorNavigationTHUScenario. Thus, the related behavior file where we add the new entries is called BehaviorNavigationTHUScenario.smartTcl.

The below code block describes a particular instance of a location. A location comprises information about how to approach it. In our example, the location is named refrigerator. Further name-value pairs comprise information needed for approaching that location:

(tcl-kb-update 
  :key '(is-a name) 
  :value '( 
            (is-a location)
            (name refrigerator)
            (speech "refrigerator")
            (approach-type (region))
            (approach-region-pose (6100 3500 0))
            (approach-region-dist 150)
            (approach-exact-pose (6100 3500 0))
            (approach-exact-dist 50)
            (approach-exact-safetycl 0)
            (orientation-region (position 6100 5000))
            (orientation-exact (position 6100 5000))))

The following explains in detail each line of code of the above code block:

• tcl-kb-update : SmartTCL function to add / update a key-value-pair to / stored in a knowledge base.
• :key '(is-a name): specifies which values of which keys need to match for identifying the entry to be updated (new entry added in case of no matching entry). In this example, the values of the keys is-a (which is the type) and name (which is the identifier of the instance) need to match.
• :value '(…): this now lists key-value pairs
  • (is-a location): defines that this entity is of type location
  • (name refrigerator): the name of the pose is refrigerator
  • (speech “refrigerator”): if we use text to speech, this text is used to speak out the location.
  • (approach-type (region)): approaching a location has two types i.e. region or exact. As the names indicate, the approach type exact is more accurate in reaching the given pose.
    • approach-region uses the parameters approach-region-*
    • approach-exact uses the parameters approach-exact-*
  • (approach-region-pose (6100 3500 0)): coordinates of location used with region type of approach.
  • (approach-region-dist 150): radius of circle around the goal position. If the robot enters this circle, it is considered to have reached the goal. Units are millimeters.
  • (approach-exact-pose (6100 3500 0)): same as approach-region-pose but used with exact type of approach.
  • (approach-exact-dist 50): same as approach-region-dist but used with exact type of approach.
  • (approach-exact-safetycl 0): safety clearance distance. Robot has to stay away from obstacles at least this distance. Units are millimeters.
  • (orientation-region (position 6100 5000)): the location to which the robot has to look at. This defines its final orientation. Units are millimeters.
  • (orientation-exact (position 6100 5000)): same as orientation-region but used with exact type of approach.

The following code block specifies an area. This information is useful in case of large environments as to load only those parts of the map which cover the current workspace. It is also useful to select the proper map for different floor levels. This entries are of type room.

(tcl-kb-update 
  :key '(is-a name) 
  :value '(
            (is-a room)
            (name room-1)
            (speech "Lab")
            (size (40000 40000))
            (offset (-20000 -20000))))

• (is-a room) specifies that this entry is of type room
• (name room-1) indicates the name of the area or room.
• (speech “Lab”) is used for text to speech conversion, it is not used with the flexible navigation stack.
• there needs to be a rectangular area that is big enough to cover the region called (name room-1).
  • size is the (x, y) [mm, mm] dimension of the rectangular area. This area must not be more than the size of the map.
  • offset specifies the (x, y) [mm, mm] offset of the rectangular area with respect to the origin of the coordinate system

The following image illustrate the selected region of map for different values for size and offset entries.

Apart from the information about locations, we also need to provide the information about the robot. The below code block adds a robot to the knowledge base.

(tcl-kb-update 
  :key '(is-a name) 
  :value '(
            (is-a robot)
            (name 1)
            (velocity-travelling ((0 500)(-60 60)))
            (velocity-path-navigation ((0 500)(-60 60)))
            (velocity-following  ((0 1200)(-200 200)))
            (current-room room-1)
            (current-symbolic-position nil)
            (goalid 0)
            (default-nav-map "navigation-map")
            (default-map "localization-map")))

• (is-a robot) specifies that this entry is of type robot
• (name 1) specifies the name of the robot to be 1
• velocity-* entries provide minimum and maximum linear and angular velocities for different kinds of navigation. The flexible navigation stack uses the values from velocity-travelling
• current-room is the area in which the robot currently operates
• goalid is a variable used for syncing the planner and mapper components [for experts only].
• default-nav-map specifies the map that should be used by the mapper component
• default-map specifies the map that should be used by the localization component
• in most cases, these two maps are same and only differ in name

Finally, the file BehaviorNavigationTHUScenario.smartTcl should look as follows (comprising locations such as home, refrigerator, whiteshelf, bench, table, a robot named 1 and a room named room-1):

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; SCENARIO MEMORY 
(tcl-kb-update 
  :key '(is-a name) 
  :value '( 
            (is-a location)
            (name home)
            (speech "home position")
            (approach-type (region))
            (approach-region-pose (0 0 0))
            (approach-region-dist 150)
            (approach-exact-pose (0 0 0))
            (approach-exact-dist 50)
            (approach-exact-safetycl 0)
            (orientation-region (position 1000 0))
            (orientation-exact (position 1000 0))
            (backward-dist 500)))
 
(tcl-kb-update 
  :key '(is-a name) 
  :value '( 
            (is-a location)
            (name refrigerator)
            (speech "refrigerator")
            (approach-type (region))
            (approach-region-pose (6100 3500 0))
            (approach-region-dist 150)
            (approach-exact-pose (6100 3500 0))
            (approach-exact-dist 50)
            (approach-exact-safetycl 0)
            (orientation-region (position 6100 5000))
            (orientation-exact (position 6100 5000))))
 
(tcl-kb-update 
  :key '(is-a name) 
  :value '( 
            (is-a location)
            (name whiteshelf)
            (speech "whiteshelf")
            (approach-type (region))
            (approach-region-pose (8000 -2500 0))
            (approach-region-dist 150)
            (approach-exact-pose (8000 -2500 0))
            (approach-exact-dist 50)
            (approach-exact-safetycl 0)
            (orientation-region (position 10000 -2500))
            (orientation-exact (position 10000 -2500))))
 
(tcl-kb-update 
  :key '(is-a name) 
  :value '( 
            (is-a location)
            (name bench)
            (speech "bench")
            (approach-type (region))
            (approach-region-pose (1500 3000 0))
            (approach-region-dist 150)
            (approach-exact-pose (1500 3000 0))
            (approach-exact-dist 50)
            (approach-exact-safetycl 0)
            (orientation-region (position 1500 5000))
            (orientation-exact (position 1500 5000))))
 
 
(tcl-kb-update 
  :key '(is-a name) 
  :value '( 
            (is-a location)
            (name table)
            (speech "table")
            (approach-type (region))
            (approach-region-pose (-2000 -2000 0))
            (approach-region-dist 150)
            (approach-exact-pose (-2000 -2000 0))
            (approach-exact-dist 50)
            (approach-exact-safetycl 0)
            (orientation-region (position -4000 -2000))
            (orientation-exact (position -4000 -2000))))
 
 
(tcl-kb-update 
  :key '(is-a name) 
  :value `(
            (is-a robot)
            (name 1)
            (velocity-travelling ((0 500)(-60 60)))
            (velocity-path-navigation ((0 500)(-60 60)))
            (velocity-following  ((0 1200)(-200 200)))
            (current-room room-1)
            (current-symbolic-position nil)
            (goalid 0)
            (default-nav-map "navigation-map")
            (default-map "localization-map")))
 
(tcl-kb-update 
  :key '(is-a name) 
  :value '(
            (is-a room)
            (name room-1)
            (speech "Lab")
            (size (40000 40000))
            (offset (-20000 -20000))))
 
 
 
(defun show-locations ()
  (let ((obj-list     (tcl-kb-query-all :key '(is-a) :value '((is-a location)))))
    (dolist (obj obj-list)
      (format t "~%--------------------------------~%")
      (format t "L O C A T I O N ------------------~%")
      (format t "name                       : ~s ~%" (get-value obj 'name))
      (format t "  type                     : ~s ~%" (get-value obj 'type))
      (format t "  approach-type            : ~s ~%" (get-value obj 'approach-type))
      (format t "  approach-region-pose     : ~s ~%" (get-value obj 'approach-region-pose))
      (format t "  approach-region-dist     : ~s ~%" (get-value obj 'approach-region-dist))
      (format t "  approach-exact-pose      : ~s ~%" (get-value obj 'approach-exact-pose))
      (format t "  approach-exact-dist      : ~s ~%" (get-value obj 'approach-exact-dist))
      (format t "  approach-exact-safetycl  : ~s ~%" (get-value obj 'approach-exact-safetycl))
      (format t "  orientation-region       : ~s ~%" (get-value obj 'orientation-region))
      (format t "  orientation-exact        : ~s ~%" (get-value obj 'orientation-exact))
      (format t "  orientation              : ~s ~%" (get-value obj 'orientation))
      (format t "  station-distance         : ~s ~%" (get-value obj 'station-distance))
      (format t "  belt-count               : ~s ~%" (get-value obj 'belt-count)))))
 
 
(defun show-robots ()
  (let ((robot-list (tcl-kb-query-all :key '(is-a) :value '((is-a robot)))))
    (dolist (robot robot-list)
    (format t "~%--------------------------------~%")
    (format t "R O B O T ------------------------~%")
    (format t "  name                   : ~s ~%" (get-value robot 'name))
    (format t "  velocity-travelling    : ~s ~%" (get-value robot 'velocity-travelling))
    (format t "  current-room           : ~s ~%" (get-value robot 'current-room))
    (format t "  curr-s-loc             : ~s ~%" (get-value robot 'current-symbolic-position)))))
 
 
;; SCENARIO MEMORY 
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

Now you can proceed with tutorial «to be added»