Python 3 Interface for the Robotics Cape on the Beaglebone Black and the Beaglebone Blue

Transcription

1 Python 3 Interface for the Robotics Cape on the Beaglebone Black and the Beaglebone Blue Mauricio C. de Oliveira Aug 09, 2017

2

3 CONTENTS: 1 Introduction Installation Modules Module rcpy Module rcpy.clock Module rcpy.gpio Module rcpy.button Module rcpy.led Module rcpy.encoder Module rcpy.motor Module rcpy.servo Module rcpy.mpu Indices and tables 27 Python Module Index 29 Index 31 i

4 ii

5 CHAPTER ONE INTRODUCTION This package supports the hardware on the Robotics Cape running on a Beaglebone Black or a Beaglebone Blue. 1.1 Installation See for installation instructions. 1

6 2 Chapter 1. Introduction

7 CHAPTER TWO MODULES 2.1 Module rcpy This module is responsible to loading and initializing all hardware devices associated with the Robotics Cape or Beagelbone Blue. Just type: import rcpy to load the module. After loading the Robotics Cape is left at the state rcpy.paused. It will also automatically cleanup after you exit your program. You can add additional function to be called by the cleanup routine using rcpy. add_cleanup() Constants rcpy.idle rcpy.running rcpy.paused rcpy.exiting Low-level functions rcpy.get_state() Get the current state, one of rcpy.idle, rcpy.running, rcpy.paused, rcpy.exiting. rcpy.set_state(state) Set the current state, state is one of rcpy.idle, rcpy.running, rcpy.paused, rcpy.exiting. rcpy.exit() Set state to rcpy.exiting. rcpy.add_cleanup(fun, pars) fun function to call at cleanup pars list of positional parameters to pass to function fun Add function fun and parameters pars to the list of cleanup functions. 3

8 2.2 Module rcpy.clock This module provides a class rcpy.clock.clock that can be used to run actions periodically. Actions must inherit from the class rcpy.clock.action and implement the method rcpy.clock.action.run(). Examples of objects that inherit from rcpy.clock.action are rcpy.led.led and rcpy.servo.servo. For example: import rcpy.clock as clock from rcpy.led import red clk = clock.clock(red) clk.start() will start a thread that will blink the red LED every second. The command: clk.stop() will stop the LED blinking. The subclass rcpy.led.blink will in addition turn off the led after stopping Classes class rcpy.clock.action rcpy.clock.action represents and action. run() Run the action. class rcpy.clock.actions(*actions) Bases rcpy.clock.action rcpy.clock.actions represents a sequence of actions. actions comma separated list of actions. class rcpy.clock.clock(action, period) Bases threading.thread rcpy.clock.clock executes actions periodically. set_period(period) action (Action) the action to be executed period (int) the period in seconds (default 1 second) period (float) period in seconds Set action period. toggle() Toggle action on and off. Call toggle again to resume or stop action. start() Start the action thread. stop() Stop the action thread. Action cannot resume after calling rcpy.led.blink.stop(). Use rcpy. clock.clock.toggle() to temporarily interrupt an action. 4 Chapter 2. Modules

9 2.3 Module rcpy.gpio This module provides an interface to the GPIO pins used by the Robotics Cape. There are low level functions which closely mirror the ones available in the C library and also Classes that provide a higher level interface. For example: import rcpy.gpio as gpio pause_button = gpio.input(gpio.pause_btn) imports the module and create an rcpy.gpio.input object corresponding to the PAUSE button on the Robotics Cape. The command: if pause_button.low(): print('got <PAUSE>!') waits forever until the PAUSE button on the Robotics Cape becomes rcpy.gpio.low, which happens when it is pressed. The following slightly modified version: try: if pause_button.low(timeout = 2000): print('got <PAUSE>!') except gpio.inputtimeout: print('timed out!') waits for at most 2000 ms, i.e. 2 s, before giving up, which one can detect by catching the exception rcpy.gpio. InputTimeout. In the same vein, the method rcpy.gpio.input.high() would wait for the button PAUSE to become rcpy. gpio.high. For instance: if pause_button.high(): print('<pause> got high!') waits forever until the PAUSE button on the Robotics Cape is released. Note that nothing will print if you first have to press the button before releasing because rcpy.gpio.input.high() returns False after the first input event, which in this case would correspond to the GPIO pin going rcpy.gpio.low. The methods rcpy.gpio.input.is_low() and rcpy.gpio.input.is_high() are non-blocking versions of the above methods. For example: import time while True: if pause_button.is_low(): print('got <PAUSE>!') break time.sleep(1) checks the status of the button PAUSE every 1 s and breaks when PAUSE is pressed. A much better way to handle such events is to use the class rcpy.gpio.inputevent. For example: class MyInputEvent(gpio.InputEvent): def action(self, event): print('got <PAUSE>!') defines a class that can be used to print Got <PAUSE>! every time an input event happens. To connect this class with the particular event that the PAUSE button is pressed instantiate: 2.3. Module rcpy.gpio 5

10 pause_event = MyInputEvent(pause_button, gpio.inputevent.low) which will cause the method action of the MyInputEvent class be called every time the state of the pause_button becomes rcpy.gpio.low. The event handler must be started by calling: pause_event.start() and it can be stopped by: pause_event.stop() The event handler automatically runs on a separate thread, which means that the methods rcpy.gpio. InputEvent.start() and rcpy.gpio.inputevent.stop() are non-blocking, that is they return immediately. The class rcpy.gpio.inputevent defines two types of events: rcpy.gpio.inputevent.high and rcpy.gpio.inputevent.low. Note that these are not the same as rcpy.gpio.high and rcpy.gpio. LOW! It is often convenient to import the base class rcpy.gpio.inputevent: from rcpy.gpio import InputEvent Alternatively one could have created an input event handler by passing a function to the argument target of rcpy. gpio.inputevent as in: def pause_action(input, event): if event == InputEvent.LOW: print('<pause> went LOW') elif event == InputEvent.HIGH: print('<pause> went HIGH') pause_event = InputEvent(pause_button, InputEvent.LOW InputEvent.HIGH, target = pause_action) The function pause_action will be called when pause_button generates either event rcpy.gpio.inputevent. HIGH or rcpy.gpio.inputevent.low because the events passed to the the constructor InputEvent were combined using the logical or operator, as in: InputEvent.LOW InputEvent.HIGH, The function pause_action decides on the type of event by checking the variable event. This event handler should be started and stopped using rcpy.gpio.inputevent.start() and rcpy.gpio.inputevent.stop() as before. Additional positional or keyword arguments can be passed as in: def pause_action_with_parameter(input, event, parameter): print('got <PAUSE> with {}!'.format(parameter)) pause_event = InputEvent(pause_button, InputEvent.LOW, target = pause_action_with_parameter, vargs = ('some parameter',)) See also rcpy.button.button for a better interface for working with the Robotics Cape buttons. 6 Chapter 2. Modules

11 2.3.1 Constants rcpy.gpio.high Logic high level; equals 1. rcpy.gpio.low Logic low level; equals 0. rcpy.gpio.debounce_interval Interval in ms to be used for debouncing (Default 0.5ms) Classes class rcpy.gpio.inputtimeout Exception representing an input timeout event. class rcpy.gpio.input(pin) pin (int) GPIO pin rcpy.gpio.input represents one of the GPIO input pins in the Robotics Cape or Beaglebone Blue. is_high() is_low() Returns True if pin is equal to rcpy.gpio.high and False if pin is rcpy.gpio.low Returns True if pin is equal to rcpy.gpio.low and False if pin is rcpy.gpio.high high_or_low(debounce = 0, timeout = None) debounce (int) number of times to read input for debouncing (default 0) timeout (int) timeout in milliseconds (default None) Raises rcpy.gpio.inputtimeout if more than timeout ms have elapsed without the input changing Returns the new state as rcpy.gpio.high or rcpy.gpio.low Wait for pin to change state. If timeout is not None wait at most timeout ms otherwise wait forever until the input changes. high(debounce = 0, timeout = None) debounce (int) number of times to read input for debouncing (default 0) timeout (int) timeout in milliseconds (default None) Raises rcpy.gpio.inputtimeout if more than timeout ms have elapsed without the input changing Returns True if the new state is rcpy.gpio.high and False if the new state is rcpy. gpio.low Wait for pin to change state. If timeout is not None wait at most timeout ms otherwise wait forever until the input changes. low(debounce = 0, timeout = None) 2.3. Module rcpy.gpio 7

12 debounce (int) number of times to read input for debouncing (default 0) timeout (int) timeout in milliseconds (default None) Raises rcpy.gpio.inputtimeout if more than timeout ms have elapsed without the input changing Returns True if the new state is rcpy.gpio.low and False if the new state is rcpy. gpio.high Wait for pin to change state. If timeout is not None wait at most timeout ms otherwise wait forever until the input changes. class rcpy.gpio.inputevent(input, event, debounce = 0, timeout = None, target = None, vargs = (), kwargs = {}) Bases threading.thread rcpy.gpio.inputevent is an event handler for GPIO input events. input (int) instance of rcpy.gpio.input event (int) either rcpy.gpio.inputevent.high or rcpy.gpio. InputEvent.LOW debounce (int) number of times to read input for debouncing (default 0) timeout (int) timeout in milliseconds (default None) target (int) callback function to run in case input changes (default None) vargs (int) positional arguments for function target (default ()) kwargs (int) keyword arguments for function target (default {}) LOW Event representing change to a low logic level. HIGH Event representing change to a high logic level. action(event, *vargs, **kwargs) event either rcpy.gpio.high or rcpy.gpio.low vargs variable positional arguments kwargs variable keyword arguments Action to perform when event is detected. start() Start the input event handler thread. stop() Attempt to stop the input event handler thread. Once it has stopped it cannot be restarted. 8 Chapter 2. Modules

13 2.3.3 Low-level functions rcpy.gpio.set(pin, value) pin (int) GPIO pin value (int) value to set the pin (rcpy.gpio.high or rcpy.gpio.low) Raises rcpy.gpio.error if it cannot write to pin Set GPIO pin to the new value. rcpy.gpio.get(pin) pin (int) GPIO pin Raises rcpy.gpio.error if it cannot read from pin Returns the current value of the GPIO pin This is a non-blocking call. rcpy.gpio.read(pin, timeout = None) Raises pin (int) GPIO pin timeout (int) timeout in milliseconds (default None) rcpy.gpio.error if it cannot read from pin rcpy.gpio.inputtimeout if more than timeout ms have elapsed without the input changing Returns the new value of the GPIO pin Wait for value of the GPIO pin to change. This is a blocking call. 2.4 Module rcpy.button This module provides an interface to the PAUSE and MODE buttons in the Robotics Cape. The command: import rcpy.button as button imports the module. The Module rcpy.button provides objects corresponding to the PAUSE and MODE buttons on the Robotics Cape. Those are rcpy.button.pause and rcpy.button.mode. One can import those objects directly using: from rcpy.button import mode, pause After importing these objects: if mode.pressed(): print('<mode> pressed!') waits forever until the MODE button on the Robotics Cape is pressed and: 2.4. Module rcpy.button 9

14 if mode.released(): print('<mode> released!') waits forever until the MODE button on the Robotics Cape is released. Note that nothing will print if you first have to press the button before releasing because rcpy.button.button.released() returns False after the first input event, which in this case would correspond to the GPIO pin associated to the button going rcpy.button. PRESSED. rcpy.button.button.pressed() and rcpy.button.button.released() also raise the exception rcpy.gpio.inputtimeout if the argument timeout is used as in: import rcpy.gpio as gpio try: if mode.pressed(timeout = 2000): print('<mode> pressed!') except gpio.inputtimeout: print('timed out!') which waits for at most 2000 ms, i.e. 2 s, before giving up. The methods rcpy.button.button.is_pressed() and rcpy.button.button.is_released() are non-blocking versions of the above methods. For example: import time while True: if mode.is_pressed(): print('<mode> pressed!') break time.sleep(1) checks the status of the button MODE every 1 s and breaks when MODE is pressed. As with Module rcpy.clock, a much better way to handle such events is to use event handlers, in the case of buttons the class rcpy.button. ButtonEvent. For example: class MyButtonEvent(button.ButtonEvent): def action(self, event): print('got <PAUSE>!') defines a class that can be used to print Got <PAUSE>! every time the PAUSE button is pressed. To instantiate and start the event handler use: pause_event = MyButtonEvent(pause, button.buttonevent.pressed) pause_event.start() Note that the event rcpy.button.buttonevent.pressed was used so that MyButtonEvent.action is called only when the PAUSE button is pressed. The event handler can be stopped by calling: pause_event.stop() Alternatively one could have created an input event handler by passing a function to the argument target of rcpy. button.buttonevent as in: from rcpy.button import ButtonEvent def pause_action(input, event): if event == ButtonEvent.PRESSED: print('<pause> pressed!') elif event == ButtonEvent.RELEASED: 10 Chapter 2. Modules

15 print('<pause> released!') pause_event = ButtonEvent(pause, ButtonEvent.PRESSED ButtonEvent.RELEASED, target = pause_action) This event handler should be started and stopped using rcpy.button.buttonevent.start() and rcpy. button.buttonevent.stop() as before. Additional positional or keyword arguments can be passed as in: def pause_action_with_parameter(input, event, parameter): print('got <PAUSE> with {}!'.format(parameter)) pause_event = ButtonEvent(pause, ButtonEvent.PRESSED, target = pause_action_with_parameter, vargs = ('some parameter',)) The main difference between Module rcpy.button and Module rcpy.clock is that Module rcpy.button defines the constants rcpy.button.pressed and rcpy.button.released, the events rcpy.button.buttonevent. PRESSED and rcpy.button.buttonevent.released, and its classes handle debouncing by default Constants rcpy.button.pause rcpy.button.button representing the Robotics Cape PAUSE button. rcpy.button.mode rcpy.button.button representing the Robotics Cape MODE button. rcpy.button.pressed State of a pressed button; equal to rcpy.gpio.low. rcpy.button.released State of a released button; equal to rcpy.gpio.high. rcpy.button.debounce Number of times to test for deboucing (Default 3) Classes class rcpy.button.button Bases rcpy.gpio.input rcpy.button.button represents buttons in the Robotics Cape or Beaglebone Blue. is_pressed() is_released() Returns True if button state is equal to rcpy.button.pressed and False if pin is rcpy.button.released Returns True if button state is equal to rcpy.button.released and False if pin is rcpy.button.pressed pressed_or_released(debounce = rcpy.button.debounce, timeout = None) 2.4. Module rcpy.button 11

16 debounce (int) number of times to read input for debouncing (default rcpy.button.debounce) timeout (int) timeout in milliseconds (default None) Raises rcpy.gpio.inputtimeout if more than timeout ms have elapsed without the button state changing Returns the new state as rcpy.button.pressed or rcpy.button.released Wait for button state to change. If timeout is not None wait at most timeout ms otherwise wait forever until the input changes. pressed(debounce = rcpy.button.debounce, timeout = None) debounce (int) number of times to read input for debouncing (default rcpy.button.debounce) timeout (int) timeout in milliseconds (default None) Raises rcpy.gpio.inputtimeout if more than timeout ms have elapsed without the button state changing. Returns True if the new state is rcpy.button.pressed and False if the new state is rcpy.button.released Wait for button state to change. If timeout is not None wait at most timeout ms otherwise wait forever until the input changes. released(debounce = rcpy.button.debounce, timeout = None) debounce (int) number of times to read input for debouncing (default rcpy.button.debounce) timeout (int) timeout in milliseconds (default None) Raises rcpy.gpio.inputtimeout if more than timeout ms have elapsed without the button state changing. Returns True if the new state is rcpy.button.released and False if the new state is rcpy.button.pressed Wait for button state to change. If timeout is not None wait at most timeout ms otherwise wait forever until the input changes. class rcpy.button.buttonevent(input, event, debounce = rcpy.button.debounce, timeout = None, target = None, vargs = (), kwargs = {}) Bases rcpy.gpio.inputevent input (int) instance of rcpy.gpio.input event (int) either rcpy.button.buttonevent.pressed or rcpy.button. ButtonEvent.RELEASED debounce (int) number of times to read input for debouncing (default rcpy.button.debounce) timeout (int) timeout in milliseconds (default None) 12 Chapter 2. Modules

17 target (int) callback function to run in case input changes (default None) vargs (int) positional arguments for function target (default ()) kwargs (int) keyword arguments for function target (default {}) rcpy.button.buttonevent is an event handler for button events. PRESSED Event representing pressing a button; equal to rcpy.gpio.inputevent.low. RELEASED Event representing releasing a button; equal to rcpy.gpio.inputevent.high. action(event, *vargs, **kwargs) event either rcpy.button.pressed or rcpy.button.released vargs variable positional arguments kwargs variable keyword arguments Action to perform when event is detected. start() Start the input event handler thread. stop() Attempt to stop the input event handler thread. Once it has stopped it cannot be restarted. 2.5 Module rcpy.led This module provides an interface to the RED and GREEN buttons in the Robotics Cape. The command: import rcpy.led as led imports the module. The Module rcpy.led provides objects corresponding to the RED and GREEN buttons on the Robotics Cape, namely rcpy.led.red and rcpy.led.green. It may be convenient to import one or all of these objects as in: from rcpy.led import red, green For example: red.on() turns the RED LED on and: green.off() turns the GREEN LED off. Likewise: green.is_on() returns True if the GREEN LED is on and: red.is_off() 2.5. Module rcpy.led 13

18 returns True if the RED LED is off. This module also provides the class rcpy.led.blink to handle LED blinking. It spawns a thread that will keep LEDs blinking with a given period. For example: blink = led.blink(red,.5) blink.start() starts blinking the RED LED every 0.5 seconds. One can stop or resume blinking by calling rcpy.led.blink. toggle() as in: blink.toggle() or call: blink.stop() to permanently stop the blinking thread. One can also instantiate an rcpy.led.blink object by calling rcpy.led.led.blink() as in: blink = red.blink(.5) which returns an instance of rcpy.led.blink. rcpy.led.led.blink() automatically calls rcpy.led. Blink.start() Constants rcpy.led.red rcpy.led.led representing the Robotics Cape RED LED. rcpy.led.green rcpy.led.led representing the Robotics Cape GREEN LED. rcpy.led.on State of an on LED; equal to rcpy.gpio.high. rcpy.led.off State of an off led; equal to rcpy.gpio.low Classes class rcpy.led.led(output, state = rcpy.led.off) Bases rcpy.gpio.output output GPIO pin state initial LED state rcpy.led.led represents LEDs in the Robotics Cape or Beaglebone Blue. is_on() Returns True if LED is on and False if LED is off is_off() 14 Chapter 2. Modules

19 Returns True if LED is off and False if LED is on on() Change LED state to rcpy.led.on. off() Change LED state to rcpy.led.off. toggle() Toggle current LED state. blink(period) period (float) period of blinking Returns an instance of rcpy.led.blink. Blinks LED with a period of period seconds. class rcpy.led.blink(led, period) Bases rcpy.clock.clock rcpy.led.blink toggles led on and off periodically. led (LED) the led to toggle period (int) the period in seconds 2.6 Module rcpy.encoder This module provides an interface to the four encoder channels in the Robotics Cape. The command: import rcpy.encoder as encoder imports the module. The Module rcpy.encoder provides objects corresponding to the each of the encoder channels on the Robotics Cape, namely rcpy.encoder.encoder1, rcpy.encoder.encoder2, rcpy.encoder. encoder3, and rcpy.encoder.encoder4. It may be convenient to import one or all of these objects as in: from rcpy.encoder import encoder2 The current encoder count can be obtained using: encoder2.get() One can also reset the count to zero using: encoder2.reset() or to an arbitrary count using: encoder2.set(1024) after which: encoder2.get() will return Module rcpy.encoder 15

20 2.6.1 Constants rcpy.encoder.encoder1 rcpy.encoder.encoder representing the Robotics Cape Encoder 1. rcpy.encoder.encoder2 rcpy.encoder.encoder representing the Robotics Cape Encoder 2. rcpy.encoder.encoder3 rcpy.encoder.encoder representing the Robotics Cape Encoder 3. rcpy.encoder.encoder4 rcpy.encoder.encoder representing the Robotics Cape Encoder Classes class rcpy.encoder.encoder(channel, count = None) output encoder channel (1 through 4) state initial encoder count (Default None) rcpy.encoder.encoder represents encoders in the Robotics Cape or Beaglebone Blue. get() Returns current encoder count set(count) Set current encoder count to count. reset() Set current encoder count to Low-level functions rcpy.encoder.get(channel) channel (int) encoder channel number Returns current encoder count This is a non-blocking call. rcpy.encoder.set(channel, count = 0) channel (int) encoder channel number count (int) desired encoder count Set encoder channel count to value. 2.7 Module rcpy.motor This module provides an interface to the four motor channels in the Robotics Cape. Those control a high power PWM (Pulse Width Modulation) signal which is typically used to control DC Motors. The command: 16 Chapter 2. Modules

21 import rcpy.motor as motor imports the module. The Module rcpy.motor provides objects corresponding to the each of the motor channels on the Robotics Cape, namely rcpy.motor.motor1, rcpy.motor.motor2, rcpy.motor.motor3, and rcpy. motor.motor4. It may be convenient to import one or all of these objects as in from rcpy.motor import motor2 This is a convenience object which is equivalent to: motor2 = Motor(2) The current average voltage applied to the motor can be set using: duty = 1 motor2.set(duty) where duty is a number varying from -1 to 1 which controls the percentage of the voltage available to the Robotics Cape that should be applied on the motor. A motor can be turned off by: motor2.set(0) or using one of the special methods rcpy.motor.motor.free_spin() or rcpy.motor.motor.brake(), which can be used to turn off the motor and set it in a free-spin or braking configuration. For example: motor2.free_spin() puts motor2 in free-spin mode. In free-spin mode the motor behaves as if there were no voltage applied to its terminal, that is it is allowed to spin freely. In brake mode the terminals of the motor are short-circuited and the motor winding will exert an opposing force if the motor shaft is moved. Brake mode is essentially the same as setting the duty cycle to zero Constants rcpy.motor.motor1 rcpy.motor.motor representing the Robotics Cape Motor 1. rcpy.motor.motor2 rcpy.motor.motor representing the Robotics Cape Motor 2. rcpy.motor.motor3 rcpy.motor.motor representing the Robotics Cape Motor 3. rcpy.motor.motor4 rcpy.motor.motor representing the Robotics Cape Motor Classes class rcpy.motor.motor(channel, duty = None) output motor channel (1 through 4) state initial motor duty cycle (Default None) rcpy.motor.motor represents motors in the Robotics Cape or Beaglebone Blue Module rcpy.motor 17

22 set(duty) Set current motor duty cycle to duty. duty is a number between -1 and 1. free_spin() Stops the motor and puts it in free-spin mode. brake() Stops the motor and puts it in brake mode Low-level functions rcpy.motor.set(channel, duty) channel (int) motor channel number duty (int) desired motor duty cycle Sets the motor channel channel duty cycle to duty. This is a non-blocking call. rcpy.motor.set_free_spin(channel) channel (int) motor channel number Puts the motor channel channel in free-spin mode. This is a non-blocking call. rcpy.motor.set_brake(channel) channel (int) motor channel number Puts the motor channel channel in brake mode. This is a non-blocking call. 2.8 Module rcpy.servo This module provides an interface to the eight servo and ESC (Electronic Speed Control) channels in the Robotics Cape. The 3-pin servo connectors are not polarized so make sure the black/brown ground wire is the one closest to the Robotics Cape. The command: import rcpy.servo as servo imports the module. The Module rcpy.servo provides objects corresponding to the each of the servo and ESC channels on the Robotics Cape, namely rcpy.servo.servo1 through rcpy.servo.servo8, and namely rcpy. servo.esc1 through rcpy.servo.esc8. It may be convenient to import one or all of these objects as in from rcpy.servo import servo7 This is a convenience object which is equivalent to: motor7 = Servo(7) The position of the servo can be set using: 18 Chapter 2. Modules

23 duty = 1.5 servo7.set(duty) where duty is a number varying from -1.5 to 1.5, which controls the angle of the servo. This command does not send a pulse to the servo. In fact, before you can drive servos using the Robotics Cape you need to enable power to flow to servos using: servo.enable() For safety the servo power rail is disabled by default. Do not enable the servo power rail when using brushless ESCs as they can be damaged. Typical brushless ESCs only use the ground and signal pins, so if you need to control servos and ESC simultaneously simply cut or disconnect the middle power wire from the ESC connector. Use the command: servo.disable() to turn off the servo power rail. Back to servos, you can set the duty and send a pulse to the servo at the same time using the command: duty = 1.5 servo7.pulse(duty) Alternatively, you can initiate a rcpy.clock.clock object using: period = 0.1 clk = servo7.start(period) which starts sending the current servor duty value to the servo every 0.1s. The clock can be stopped by: clk.stop() The above is equivalent to: import rcpy.clock as clock period = 0.1 clk = clock.clock(servo7, period) clk.start() Similar commands are available for ESC. For example: from rcpy.servo import esc3 duty = 1.0 esc3.pulse(duty) sends a full-throttle pulse to the ESC in channel Constants rcpy.servo.servo1 rcpy.servo.servo representing the Robotics Cape Servo 1. rcpy.servo.servo2 rcpy.servo.servo representing the Robotics Cape Servo 2. rcpy.servo.servo3 rcpy.servo.servo representing the Robotics Cape Servo Module rcpy.servo 19

24 rcpy.servo.servo4 rcpy.servo.servo representing the Robotics Cape Servo 4. rcpy.servo.servo5 rcpy.servo.servo representing the Robotics Cape Servo 5. rcpy.servo.servo6 rcpy.servo.servo representing the Robotics Cape Servo 6. rcpy.servo.servo7 rcpy.servo.servo representing the Robotics Cape Servo 7. rcpy.servo.servo8 rcpy.servo.servo representing the Robotics Cape Servo 8. rcpy.servo.esc1 rcpy.servo.esc representing the Robotics Cape ESC 1. rcpy.servo.esc2 rcpy.servo.esc representing the Robotics Cape ESC 2. rcpy.servo.esc3 rcpy.servo.esc representing the Robotics Cape ESC 3. rcpy.servo.esc4 rcpy.servo.esc representing the Robotics Cape ESC 4. rcpy.servo.esc5 rcpy.servo.esc representing the Robotics Cape ESC 5. rcpy.servo.esc6 rcpy.servo.esc representing the Robotics Cape ESC 6. rcpy.servo.esc7 rcpy.servo.esc representing the Robotics Cape ESC 7. rcpy.servo.esc8 rcpy.servo.esc representing the Robotics Cape ESC Classes class rcpy.servo.servo(channel, duty = None) output servo channel (1 through 4) state initial servo duty cycle (Default 0) rcpy.servo.servo represents servos in the Robotics Cape or Beaglebone Blue. set(duty) Set current servo duty cycle to duty. duty is a number between -1.5 and 1.5. This method does not pulse the servo. Use rcpy.servo.servo.pulse() for setting and pulsing the servo at the same time. Otherwise use a rcpy.clock.clock or the method rcpy.servo.servo.start() to create one. The value of duty corresponds to the following pulse widths and servo angles: 20 Chapter 2. Modules

25 input width angle direction us 90 deg counter-clockwise us 60 deg counter-clockwise us 0 deg neutral us 60 deg clockwise us 90 deg clockwise pulse(duty) Set current servo duty cycle to duty and send a single pulse to the servo. run() Send a single pulse to the servo using the current value of duty. start(period) period (float) period Returns an instance of rcpy.clock.clock. Pulses servo periodically every period seconds. class rcpy.servo.esc(channel, duty = None) output ESC channel (1 through 4) state initial ESC duty cycle (Default 0) rcpy.servo.esc represents ESCs in the Robotics Cape or Beaglebone Blue. set(duty) Set current ESC duty cycle to duty, in which duty is a number between -0.1 and 1.0. This method does not pulse the ESC. Use rcpy.servo.esc.pulse() for setting and pulsing the ESC at the same time. Otherwise use a rcpy.clock.clock or the method rcpy.servo.esc.start() to create one. The value of duty corresponds to the following pulse widths and servo angles: input width power status us armed idle us 0% off us 50% half-throttle us 100% full-throttle pulse(duty) Set current ESC duty cycle to duty and send a single pulse to the ESC. run() Send a single pulses to the ESC using the current value of duty. start(period) period (float) period Returns an instance of rcpy.clock.clock. Pulses ESC periodically every period seconds Low-level functions rcpy.servo.enable() Enables the servo power rail. Be careful when connecting ESCs! 2.8. Module rcpy.servo 21

26 rcpy.servo.disable() Disables the servo power rail. rcpy.servo.pulse(channel, duty) channel (int) servo channel number duty (int) desired servo duty cycle Sends a normalized pulse to the servo channel channel, in which duty is a float varying from -1.5 to 1.5. See rcpy.servo.servo.set() for details. This is a non-blocking call. rcpy.servo.pulse_all(channel, duty) duty (int) desired servo duty cycle Sends a normalized pulse to all servo channels, in which duty is a float varying from -1.5 to 1.5. See rcpy. servo.servo.set() for details. This is a non-blocking call. rcpy.servo.esc_pulse(channel, duty) channel (int) servo channel number duty (int) desired ESC duty cycle Sends a normalized pulse to the ESC channel channel, in which duty is a float varying from -0.1 to 1.5. See rcpy.servo.esc.set() for details. This is a non-blocking call. rcpy.servo.esc_pulse_all(channel, duty) duty (int) desired ESC duty cycle Sends a normalized pulse to all ESC channels, in which duty is a float varying from -0.1 to 1.5. See rcpy. servo.esc.set() for details. This is a non-blocking call. rcpy.servo.oneshot_pulse(channel, duty) channel (int) ESC channel number duty (int) desired ESC duty cycle Sends a normalized oneshot pulse to the ESC channel channel, in which duty is a float varying from -0.1 to 1.0. This is a non-blocking call. rcpy.servo.oneshot_pulse_all(channel, duty) duty (int) desired ESC duty cycle Sends a normalized oneshot pulse to all ESC channels, in which duty is a float varying from -0.1 to 1.0. This is a non-blocking call. rcpy.servo.pulse_us(channel, us) 22 Chapter 2. Modules

27 channel (int) servo channel number us (int) desired servo duty cycle is μ s Sends a pulse of duration us μ s to all servo channels. This is a non-blocking call. This is a non-blocking call. rcpy.servo.pulse_us_all(channel, us) us (int) desired servo duty cycle is μ s Sends a pulse of duration us μ s to all servo channels. This is a non-blocking call. 2.9 Module rcpy.mpu9250 This module provides an interface to the on-board MPU-9250 Nine-Axis (Gyro + Accelerometer + Compass) MEMS device. The command: import rcpy.mpu9250 as mpu9250 imports the module. IMPORTANT: Beware that due to the way the Robotics Cape is written objects of the class rcpy.mpu9250.imu are singletons, that is they all refer to the same instance. Setup can be done at creation, such as in imu = mpu9250.imu(enable_dmp = True, dmp_sample_rate = 4, enable_magnetometer = True) which starts and initializes the MPU-9250 to use its DMP (Dynamic Motion Processor) to provide periodic readings at a rate of 4 Hz and also its magnetometer. The data can be read using: imu.read() which performs a blocking call and can be used to synchronize execution with the DMP. For example: while True: data = imu.read() print('heading = {}'.format(data['head'])) will print the current heading at a rate of 4 Hz. More details about the configuration options and the format of the data can be obtained in the help for the functions rcpy.mpu9250.initialize() and rcpy.mpu9250.read() Constants The following constants can be used to set the accelerometer full scale register: rcpy.mpu9250.accel_fsr_2g rcpy.mpu9250.accel_fsr_4g rcpy.mpu9250.accel_fsr_8g rcpy.mpu9250.accel_fsr_16g 2.9. Module rcpy.mpu

28 The following constants can be used to set the gyroscope full scale register: rcpy.mpu9250.gyro_fsr_250dps rcpy.mpu9250.gyro_fsr_500dps rcpy.mpu9250.gyro_fsr_1000dps rcpy.mpu9250.gyro_fsr_2000dps The following constants can be used to set the accelerometer low-pass filter: rcpy.mpu9250.accel_dlpf_off rcpy.mpu9250.accel_dlpf_184 rcpy.mpu9250.accel_dlpf_92 rcpy.mpu9250.accel_dlpf_41 rcpy.mpu9250.accel_dlpf_20 rcpy.mpu9250.accel_dlpf_10 rcpy.mpu9250.accel_dlpf_5 The following constants can be used to set the gyroscope low-pass filter: rcpy.mpu9250.gyro_dlpf_off rcpy.mpu9250.gyro_dlpf_184 rcpy.mpu9250.gyro_dlpf_92 rcpy.mpu9250.gyro_dlpf_41 rcpy.mpu9250.gyro_dlpf_20 rcpy.mpu9250.gyro_dlpf_10 rcpy.mpu9250.gyro_dlpf_5 The following constants can be used to set the imu orientation: rcpy.mpu9250.orientation_z_up rcpy.mpu9250.orientation_z_down rcpy.mpu9250.orientation_x_up rcpy.mpu9250.orientation_x_down rcpy.mpu9250.orientation_y_up rcpy.mpu9250.orientation_y_down rcpy.mpu9250.orientation_x_forward rcpy.mpu9250.orientation_x_back Classes class rcpy.mpu9250.imu(**kwargs) kwargs (kwargs) keyword arguments rcpy.mpu9250.imu represents the MPU-9250 in the Robotics Cape or Beaglebone Blue. Any keyword accepted by rcpy.mpu9250.initialize() can be given. 24 Chapter 2. Modules

29 set(**kwargs) kwargs (kwargs) keyword arguments Set current MPU-9250 parameters. Any keyword accepted by rcpy.mpu9250.initialize() can be given. read() Returns dictionary with current MPU-9250 measurements Dictionary is constructed as in rcpy.mpu9250.read() Low-level functions rcpy.mpu9250.initialize(accel_fsr, gyro_fsr, accel_dlpf, gyro_dlpf, enable_magnetometer, orientation, compass_time_constant, dmp_interrupt_priority, dmp_sample_rate, show_warnings, enable_dmp, enable_fusion) accel_fsr (int) accelerometer full scale gyro_fsr (int) gyroscope full scale accel_dlpf (int) accelerometer low-pass filter gyro_dlpf (int) gyroscope low-pass filter enable_magnetometer (bool) True enables the magnetometer orientation (int) imu orientation compass_time_constant (float) compass time-constant dmp_interrupt_priority (int) DMP interrupt priority dmp_sample_rate (int) DMP sample rate show_warnings (int) True shows warnings enable_dmp (bool) True enables the DMP enable_fusion (bool) True enables data fusion algorithm Configure and initialize the MPU All parameters are optional. Default values are obtained by calling the rc_get_default_imu_config() from the Robotics Cape library. rcpy.mpu9250.power_off() Powers off the MPU-9250 rcpy.mpu9250.read_accel_data() Returns list with three-axis acceleration in m/s 2 This function forces the MPU-9250 registers to be read. rcpy.mpu9250.read_gyro_data() Returns list with three-axis angular velocities in deg/s This function forces the MPU-9250 registers to be read. rcpy.mpu9250.read_mag_data() 2.9. Module rcpy.mpu

30 Raises mup9250error if magnetometer is disabled Returns list with 3D magnetic field vector in μt This function forces the MPU-9250 registers to be read. rcpy.mpu9250.read_imu_temp() Returns the imu temperature in deg C This function forces the MPU-9250 registers to be read. rcpy.mpu9250.read() Returns dictionary with the imu data; the keys in the dictionary depend on the current configuration If the magnetometer is enabled the dictionary contains the following keys: accel: 3-axis accelerations (m/s 2 ) gyro: 3-axis angular velocities (degree/s) mag: 3D magnetic field vector in (μt) quat: orientation quaternion tb: pitch/roll/yaw X/Y/Z angles (radians) head: heading from magnetometer (radians) If the magnetometer is not enabled the keys mag and head are not present. This function forces the MPU-9250 registers to be read only if the DMP is disabled. Otherwise it returns the latest DMP data. It is a blocking call. 26 Chapter 2. Modules

31 CHAPTER THREE INDICES AND TABLES genindex modindex search 27

32 28 Chapter 3. Indices and tables

33 PYTHON MODULE INDEX r rcpy, 3 rcpy.button, 9 rcpy.clock, 4 rcpy.encoder, 15 rcpy.gpio, 5 rcpy.led, 13 rcpy.motor, 16 rcpy.mpu9250, 23 rcpy.servo, 18 29

34 30 Python Module Index

35 INDEX A ACCEL_DLPF_10 (in module rcpy.mpu9250), 24 ACCEL_DLPF_184 (in module rcpy.mpu9250), 24 ACCEL_DLPF_20 (in module rcpy.mpu9250), 24 ACCEL_DLPF_41 (in module rcpy.mpu9250), 24 ACCEL_DLPF_5 (in module rcpy.mpu9250), 24 ACCEL_DLPF_92 (in module rcpy.mpu9250), 24 ACCEL_DLPF_OFF (in module rcpy.mpu9250), 24 ACCEL_FSR_16G (in module rcpy.mpu9250), 23 ACCEL_FSR_2G (in module rcpy.mpu9250), 23 ACCEL_FSR_4G (in module rcpy.mpu9250), 23 ACCEL_FSR_8G (in module rcpy.mpu9250), 23 Action (class in rcpy.clock), 4 action() (rcpy.button.buttonevent method), 13 action() (rcpy.gpio.inputevent method), 8 Actions (class in rcpy.clock), 4 add_cleanup() (in module rcpy), 3 B Blink (class in rcpy.led), 15 blink() (rcpy.led.led method), 15 brake() (rcpy.motor.motor method), 18 Button (class in rcpy.button), 11 ButtonEvent (class in rcpy.button), 12 ButtonEvent.PRESSED (in module rcpy.button), 13 ButtonEvent.RELEASED (in module rcpy.button), 13 C Clock (class in rcpy.clock), 4 D DEBOUNCE (in module rcpy.button), 11 DEBOUNCE_INTERVAL (in module rcpy.gpio), 7 disable() (in module rcpy.servo), 21 E enable() (in module rcpy.servo), 21 Encoder (class in rcpy.encoder), 16 encoder1 (in module rcpy.encoder), 16 encoder2 (in module rcpy.encoder), 16 encoder3 (in module rcpy.encoder), 16 encoder4 (in module rcpy.encoder), 16 ESC (class in rcpy.servo), 21 esc1 (in module rcpy.servo), 20 esc2 (in module rcpy.servo), 20 esc3 (in module rcpy.servo), 20 esc4 (in module rcpy.servo), 20 esc5 (in module rcpy.servo), 20 esc6 (in module rcpy.servo), 20 esc7 (in module rcpy.servo), 20 esc8 (in module rcpy.servo), 20 esc_pulse() (in module rcpy.servo), 22 esc_pulse_all() (in module rcpy.servo), 22 exit() (in module rcpy), 3 EXITING (in module rcpy), 3 F free_spin() (rcpy.motor.motor method), 18 G get() (in module rcpy.encoder), 16 get() (in module rcpy.gpio), 9 get() (rcpy.encoder.encoder method), 16 get_state() (in module rcpy), 3 green (in module rcpy.led), 14 GYRO_DLPF_10 (in module rcpy.mpu9250), 24 GYRO_DLPF_184 (in module rcpy.mpu9250), 24 GYRO_DLPF_20 (in module rcpy.mpu9250), 24 GYRO_DLPF_41 (in module rcpy.mpu9250), 24 GYRO_DLPF_5 (in module rcpy.mpu9250), 24 GYRO_DLPF_92 (in module rcpy.mpu9250), 24 GYRO_DLPF_OFF (in module rcpy.mpu9250), 24 GYRO_FSR_1000DPS (in module rcpy.mpu9250), 24 GYRO_FSR_2000DPS (in module rcpy.mpu9250), 24 GYRO_FSR_250DPS (in module rcpy.mpu9250), 24 GYRO_FSR_500DPS (in module rcpy.mpu9250), 24 H HIGH (in module rcpy.gpio), 7 high() (rcpy.gpio.input method), 7 high_or_low() (rcpy.gpio.input method), 7 31

36 I IDLE (in module rcpy), 3 IMU (class in rcpy.mpu9250), 24 initialize() (in module rcpy.mpu9250), 25 Input (class in rcpy.gpio), 7 InputEvent (class in rcpy.gpio), 8 InputEvent.HIGH (in module rcpy.gpio), 8 InputEvent.LOW (in module rcpy.gpio), 8 InputTimeout (class in rcpy.gpio), 7 is_high() (rcpy.gpio.input method), 7 is_low() (rcpy.gpio.input method), 7 is_off() (rcpy.led.led method), 14 is_on() (rcpy.led.led method), 14 is_pressed() (rcpy.button.button method), 11 is_released() (rcpy.button.button method), 11 L LED (class in rcpy.led), 14 LOW (in module rcpy.gpio), 7 low() (rcpy.gpio.input method), 7 M mode (in module rcpy.button), 11 Motor (class in rcpy.motor), 17 motor1 (in module rcpy.motor), 17 motor2 (in module rcpy.motor), 17 motor3 (in module rcpy.motor), 17 motor4 (in module rcpy.motor), 17 O OFF (in module rcpy.led), 14 off() (rcpy.led.led method), 15 ON (in module rcpy.led), 14 on() (rcpy.led.led method), 15 oneshot_pulse() (in module rcpy.servo), 22 oneshot_pulse_all() (in module rcpy.servo), 22 ORIENTATION_X_BACK (in module rcpy.mpu9250), 24 ORIENTATION_X_DOWN (in module rcpy.mpu9250), 24 ORIENTATION_X_FORWARD (in module rcpy.mpu9250), 24 ORIENTATION_X_UP (in module rcpy.mpu9250), 24 ORIENTATION_Y_DOWN (in module rcpy.mpu9250), 24 ORIENTATION_Y_UP (in module rcpy.mpu9250), 24 ORIENTATION_Z_DOWN (in module rcpy.mpu9250), 24 ORIENTATION_Z_UP (in module rcpy.mpu9250), 24 P pause (in module rcpy.button), 11 PAUSED (in module rcpy), 3 power_off() (in module rcpy.mpu9250), 25 PRESSED (in module rcpy.button), 11 pressed() (rcpy.button.button method), 12 pressed_or_released() (rcpy.button.button method), 11 pulse() (in module rcpy.servo), 22 pulse() (rcpy.servo.esc method), 21 pulse() (rcpy.servo.servo method), 21 pulse_all() (in module rcpy.servo), 22 pulse_us() (in module rcpy.servo), 22 pulse_us_all() (in module rcpy.servo), 23 R rcpy (module), 3 rcpy.button (module), 9 rcpy.clock (module), 4 rcpy.encoder (module), 15 rcpy.gpio (module), 5 rcpy.led (module), 13 rcpy.motor (module), 16 rcpy.mpu9250 (module), 23 rcpy.servo (module), 18 read() (in module rcpy.gpio), 9 read() (in module rcpy.mpu9250), 26 read() (rcpy.mpu9250.imu method), 25 read_accel_data() (in module rcpy.mpu9250), 25 read_gyro_data() (in module rcpy.mpu9250), 25 read_imu_temp() (in module rcpy.mpu9250), 26 read_mag_data() (in module rcpy.mpu9250), 25 red (in module rcpy.led), 14 RELEASED (in module rcpy.button), 11 released() (rcpy.button.button method), 12 reset() (rcpy.encoder.encoder method), 16 run() (rcpy.clock.action method), 4 run() (rcpy.servo.esc method), 21 run() (rcpy.servo.servo method), 21 RUNNING (in module rcpy), 3 S Servo (class in rcpy.servo), 20 servo1 (in module rcpy.servo), 19 servo2 (in module rcpy.servo), 19 servo3 (in module rcpy.servo), 19 servo4 (in module rcpy.servo), 19 servo5 (in module rcpy.servo), 20 servo6 (in module rcpy.servo), 20 servo7 (in module rcpy.servo), 20 servo8 (in module rcpy.servo), 20 set() (in module rcpy.encoder), 16 set() (in module rcpy.gpio), 9 set() (in module rcpy.motor), 18 set() (rcpy.encoder.encoder method), 16 set() (rcpy.motor.motor method), 17 set() (rcpy.mpu9250.imu method), 24 set() (rcpy.servo.esc method), Index

37 set() (rcpy.servo.servo method), 20 set_brake() (in module rcpy.motor), 18 set_free_spin() (in module rcpy.motor), 18 set_period() (rcpy.clock.clock method), 4 set_state() (in module rcpy), 3 start() (rcpy.button.buttonevent method), 13 start() (rcpy.clock.clock method), 4 start() (rcpy.gpio.inputevent method), 8 start() (rcpy.servo.esc method), 21 start() (rcpy.servo.servo method), 21 stop() (rcpy.button.buttonevent method), 13 stop() (rcpy.clock.clock method), 4 stop() (rcpy.gpio.inputevent method), 8 T toggle() (rcpy.clock.clock method), 4 toggle() (rcpy.led.led method), 15 Index 33