Added servo support

Author: Thomas Preston

CHANGELOG

@@ -1,6 +1,16 @@
 Change Log
 ==========
 
+v0.7.4
+------
+- Fixed a bug with io_pwm() running three times faster than it should.
+  Fixes #15.
+- Added servo support.
+
+v0.7.3
+------
+- Fixed a bug with colourtail timing issue in the firmware.
+
 v0.7.2
 ------
 - Fixed a bug with colourtail using the new set_bulk.

README.md

@@ -10,3 +10,12 @@ Features:
     - Inputs/Outputs (legs, buttons, extension pins)
     - Input/Output configuration (direction and pullups)
     - Extension pin control (I/O, SPI, I2C)
+
+
+Updating Notes
+--------------
+Be sure to update the version number in:
+
+    codebug_tether/version.py
+    CHANGELOG
+    docs/conf.py

codebug_tether/__init__.py

@@ -5,4 +5,5 @@
                                  IO_PWM_OUTPUT,
                                  T2_PS_1_1,
                                  T2_PS_1_4,
-                                 T2_PS_1_16)
+                                 T2_PS_1_16,
+                                 scale)

codebug_tether/core.py

@@ -172,7 +172,7 @@ def pwm_on(self, t2_prescale, full_period, on_period):
         """Turns on the PWM generator with the given settings.
 
         :param t2_prescale: One of T2_PS_1_1, T2_PS_1_4, T2_PS_1_16
-                            Scales down the 4MHz instruction clock by
+                            Scales down the 12MHz instruction clock by
                             1, 4 or 16.
         :param full_period: 8-bit value - which is scaled up to 10-bits
                             (<< 2) - to which timer 2 will count up to
@@ -182,7 +182,7 @@ def pwm_on(self, t2_prescale, full_period, on_period):
                           full_period to control duty cycle. For
                           example:
 
-                              # 4MHz / 16 with 50% duty cycle
+                              # 12MHz / 16 with 50% duty cycle
                               codebug.pwm_on(T2_PS_1_16, 0xff, 0x200)
 
         """
@@ -205,14 +205,13 @@ def pwm_freq(self, frequency):
 
         """
         # calculate pwm settings
-        # 4 MHz / 16 = 250k ticks per second
-        full_period = int(250000 / frequency) - 1
+        # 12MHz / 16 = 750k ticks per second
+        full_period = int(750000 / frequency) - 1
         # for 50% duty cycle: shift up by 2 then /(2 i.e. 50% duty cycle)
         # on_period = (full_period << 2) / 2;
         # this is quicker
         on_period = full_period << 1
         self.pwm_on(T2_PS_1_16, full_period, on_period)
-        pass
 
     def pwm_off(self):
         """Turns off the PWM generator."""
@@ -559,3 +558,19 @@ def uart_rx_is_ready(self):
     def uart_rx_get_buffer(self, length, offset=0):
         """Returns data bytes from UART buffer."""
         return self.get_buffer(UART_RX_BUFFER_INDEX, length, offset)
+
+
+def scale(x, from_low, from_high, to_low, to_high):
+    # Hardware can only do 16bit maths
+    def limit(v):
+        max_value = 0x7fff
+        min_value = -0x8000
+        return max(min_value, min(max_value, v))
+    x, from_low, from_high, to_low, to_high = map(
+        limit, (x, from_low, from_high, to_low, to_high))
+    # do the scale
+    from_delta = from_high - from_low
+    x_offset = x - from_low
+    to_delta = to_high - to_low
+    new_x = int((x_offset * to_delta) / from_delta)
+    return to_low + new_x

codebug_tether/version.py

@@ -1 +1 @@
-__version__ = '0.7.2'
+__version__ = '0.7.4'

docs/conf.py

@@ -50,9 +50,9 @@
 #
 # The short X.Y version.
 # The short X.Y version.
-version = '0.6.0'
+version = '0.7.3'
 # The full version, including alpha/beta/rc tags.
-release = '0.6.0'
+release = '0.7.3'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/example.rst

@@ -160,6 +160,68 @@ Or you can be more specific with the duty cycle and timing::
     >>> codebug.pwm_off()
 
 
+Servos
+======
+It is possible to drive up to eight servos from CodeBug. Servos
+typically operate by sending them a PWM (Pulse Width Modulation) signal
+with a 20ms period and a 1-2ms duty cycle which controls the rotation
+angle of the servo. For example::
+
+     Pulse Length
+      <-1-2ms->
+    1+---------+
+     |         |
+    0+         +--------------------------------------+
+      <------------------20ms (50Hz)----------------->
+                         PWM Period
+
+A duty cycle of 1ms might correspond to 0° rotation and a duty cycle of
+2ms might correspond to 180° rotation. Although the precise values may
+differ depending on the type of servo.
+
+In order to drive servos from CodeBug you can call the `servo_set()`
+method which takes the servo index (which leg you are driving the
+servo from) and the the pulse length specified in N 0.5μs. For example::
+
+    >>> import codebug_tether
+    >>> from codebug_tether import (IO_DIGITAL_OUTPUT, scale)
+
+    >>> # init CodeBug and configure leg 0 to be digital output
+    >>> codebug = codebug_tether.CodeBug()
+    >>> codebug.set_leg_io(0, IO_DIGITAL_OUTPUT)
+
+    >>> # set servo on leg 0 with pulse length of 1ms (2000 * 0.5μs)
+    >>> codebug.servo_set(0, 2000)
+
+    >>> # stop driving the servo on leg 0
+    >>> codebug.servo_set(0, 0)
+
+You can use the scale function to easily calculate the required pulse
+length value like so::
+
+    >>> import codebug_tether
+    >>> from codebug_tether import (IO_DIGITAL_OUTPUT, scale)
+
+    >>> # scale 50 in the range 0-100 to the range 0-255
+    >>> scale(50, 0, 100, 0, 255)
+    127
+
+    >>> # scale 10 in the range 0-30 to the range 100-400
+    >>> scale(10, 0, 30, 100, 400)
+    200
+
+    >>> # scale 90° in the range 0-180° to the range 2000-4000 * 0.5μs
+    >>> scale(90, 0, 180, 2000, 4000)
+    3000
+
+    >>> # init CodeBug and configure leg 0 to be digital output
+    >>> codebug = codebug_tether.CodeBug()
+    >>> codebug.set_leg_io(0, IO_DIGITAL_OUTPUT)
+
+    >>> # drive the servo to be at 90 degrees
+    >>> codebug.servo_set(0, scale(90, 0, 180, 2000, 4000))
+
+
 Colour Tail
 ===========
 You can control Colour Tails (WS2812's) attached to CodeBug. By default,