Added robot option 'raw_sonars', which stops Soar from casting

out-of-range sonar values to None.

Typos & text formatting.
Added update module to docs.
ARCOS now waits several seconds for sonar values to arrive before
releasing its on_load.

docs/source/conf.py

@@ -67,9 +67,9 @@ def __getattr__(cls, name):
 # built documents.
 #
 # The short X.Y version.
-version = '1.3.9'
+version = '1.4.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.3.9'
+release = '1.4.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/soar.rst

@@ -17,3 +17,4 @@ soar
     command_line
     soar.robot
     soar.sim
+    soar.update

soar/__init__.py

@@ -15,15 +15,15 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 # soar/__init__.py
-""" Soar (Snakes on a Robot) v1.3.9
+""" Soar (Snakes on a Robot) v1.4.0
 
 An extensible Python framework for both simulating and interacting with robots.
 
 Copyright (C) 2017 Andrew Antonitis. Licensed under the LGPLv3.
 """
 
 
-__version__ = '1.3.9'
+__version__ = '1.4.0'
 blerb = 'Soar (Snakes on a Robot) v' + __version__ + ': A Python robotics framework.\n' \
                                                      'https://github.com/arantonitis/soar\n\n' \
                                                      'Copyright (C) 2017 Andrew Antonitis. Licensed under the LGPLv3.'

soar/robot/arcos.py

@@ -495,15 +495,20 @@ def start(self):
         Thread(target=self.pulse, daemon=True).start()
         Thread(target=self.update, daemon=True).start()
         self.wait_or_timeout(self.standard_event, 5.0, 'Failed to receive SIPs from the robot')
-        for i in range(5):  # Try multiple times to enable the sonars
-            if self.standard['FLAGS'] & 0x2 != 0x2:
-                self.send_command(SONAR, 1)
-                sleep(1.0)
-            else:
-                sleep(1.0)
-                return
-        if self.standard['FLAGS'] & 0x2 != 0x2:  # If they still aren't enabled, raise an exception
+        # Try multiple times to enable the sonars
+        for i in range(5):  
+            self.send_command(SONAR, 1)
+            sleep(1.0)
+            if self.standard['FLAGS'] & 0x2 == 0x2:
+                break
+        # If they still aren't enabled, raise an exception
+        if self.standard['FLAGS'] & 0x2 != 0x2:
             raise ARCOSError('Unable to enable the robot sonars.')
+        # Wait for up to 5 seconds for the sonars to return something other than 5000 mm
+        for i in range(10):
+            if any([dist != 5000 for dist in self.sonars]):
+                break
+            sleep(0.5)
 
     @staticmethod
     def wait_or_timeout(event, timeout=1.0, timeout_msg=''):

soar/robot/pioneer.py

@@ -64,6 +64,7 @@ def __init__(self, **options):
         self._last_x, self._last_y = 0, 0  # For dealing with encoder rollover
         self._x_sum, self._y_sum = 0, 0  # For dealing with encoder rollover
         self._ignore_brain_lag = False  # For making the step duration fixed
+        self._raw_sonars = False  # Whether to cast out-of-range sonars to None
         self.set_robot_options(**options)  # Sets any options passed in on construction
 
     def to_dict(self):
@@ -83,11 +84,15 @@ def set_robot_options(self, **options):
             serial_ports (list, optional): Sets the serial ports to try connecting to with the ARCOS client.
             ignore_brain_lag (bool): If `True`, a step will always be assumed to be 0.1 seconds long. Otherwise,
                 whatever duration the controller tells the robot to step is how long a step lasts.
+            raw_sonars (bool): If `True`, sonar values will not be recast to `None` when no distance was returned.
+                `5.0` will be returned instead.
         """
         if 'serial_ports' in options:
             self._serial_ports = options['serial_ports']
         if 'ignore_brain_lag' in options:
             self._ignore_brain_lag = options['ignore_brain_lag']
+        if 'raw_sonars' in options:
+            self._raw_sonars = options['raw_sonars']
 
     @property
     def fv(self):
@@ -137,14 +142,18 @@ def sonars(self):
 
         The array contains the latest distance sensed by each sonar, in order, clockwise from the robot's far left to
         its far right. Readings are given in meters and are accurate to the millimeter. If no distance was sensed by a
-        sonar, its entry in the array will be `None`.
+        sonar, its entry in the array will be `None`, unless the robot option `raw_sonars` has been set to `True`, in 
+        which case its entry will be `5.0`.
         """
         if self.simulated:  # If simulating, grab the data from the latest calculated sonars
             if not self._sonars:  # If somehow this has been called before sonars are calculated, calculate them
                 self.calc_sonars()
             return [round(s, 3) if s < self.SONAR_MAX else None for s in self._sonars]
         else:  # Otherwise grab the sonar data from the ARCOS Client
-            return [s/1000.0 if s != 5000 else None for s in self.arcos.sonars[:8]]  # Convert mm to meters
+            if self._raw_sonars:  # Don't recast out-of-range values to None
+                return [s/1000.0 for s in self.arcos.sonars[:8]]
+            else:
+                return [s/1000.0 if s != 5000 else None for s in self.arcos.sonars[:8]]  # Convert mm to meters
 
     @property
     def analogs(self):
@@ -273,7 +282,7 @@ def check_if_collided(self):  # Check if the robot has collided, and set its col
     def on_load(self):
         if self.simulated:
             self.arcos = None
-            print('Connected to Pioneer p3dx-sh MIT_0042 \'Denny\' (12.0V) [Simulated]')  # Hi Denny Freeman!
+            print('Connected to Pioneer p3dx-sh MIT_0042 \'Denny\' (12.0 V) [Simulated]')  # Hi Denny Freeman!
         else:
             try:
                 self.arcos = ARCOSClient()
@@ -290,7 +299,7 @@ def on_load(self):
                 battery_volts = self.arcos.standard['BATTERY'] / 10.0
                 # Print the standard connection message and warn if the battery is low
                 print('Connected to ' + ' '.join([config[field] for field in ['ROBOT_TYPE', 'SUBTYPE', 'NAME']])
-                      + ' \'' + name_from_sernum(serial_num) + '\' (' + str(battery_volts) + ')')
+                      + ' \'' + name_from_sernum(serial_num) + '\' (' + str(battery_volts) + ' V)')
                 if battery_volts < self.arcos.config['LOWBATTERY']/10.0:
                     printerr('WARNING: The robot\'s battery is low. Consider recharging or finding a new one.')
             except ARCOSError as e:  # If anything goes wrong, raise a SoarIOError