Welcome to robopython’s documentation!¶

robopython¶

Robo Wunderkind Python API - BLED112 USB Dongle Required

Official Robo Wunderkind Modular Robotics Kit Python Interface

For more information about Robo Wunderkind please visit https://www.robowunderkind.com/

Python 2.x Supported Python 3.x Supported

Free software: Apache Software License 2.0
Documentation: https://robopython.readthedocs.io.

Upcoming Features¶

New Module integration such as Servo, Motor, Hinge, and Camera
Fuzzy Logic Filter for Sensors/States

Getting Started¶

Install with: pip install robopython
from robopython import Robo
Create an instance of Robo object by doing: my_robo = Robo(“BLE Name”)
Test Functionality by playing a sound with: my_robo.System.play_sound(0)

Chrome OS¶

Update to latest Chrome OS
Set into Developer Mode
$ sudo dev_install python
Install ChromeBrew: https://skycocker.github.io/chromebrew/
crew install freestyle
pip install robopython
Run python as sudo for robopython to work

Troubleshooting¶

If you get an error saying No BGAPI compatable device is detected please insert the BLED112 USB dongle or switch USB ports If problem persists you can identify the COM port explicitley with my_robo = Robo(“BLE Name”, COM PORT)

Installation¶

Python and Pip Installation¶

If you don’t have pip installed, this Python installation guide can guide you through the process.

Stable release¶

To install robopython, run this command in your terminal:

$ pip install robopython

This is the preferred method to install robopython, as it will always install the most recent stable release.

From sources¶

The sources for robopython can be downloaded from the Github repo.

You can either clone the public repository:

$ git clone git://github.com/JonRobo/robopython

Or download the tarball:

$ curl  -OL https://github.com/JonRobo/robopython/tarball/master

Once you have a copy of the source, you can install it with:

$ python setup.py install

Usage¶

To use robopython in a project:

| import robopython
| OR
| from robopython import Robo
|
| my_robo = Robo("BLE_Name")

Robo¶

Create Robo Instance

from robopython import Robo

BLE_Name = “Robo1” – example BLE name

my_robo = Robo(BLE_Name)

Battery Level¶

battery_level(self)

Returns the battery level in % and the status.

>>> print my_robo.battery_level()
>>> 80, Discharging

Change BLE Name¶

change_ble_name(self, name)

name must be 16 characters or less e.g name = “Robo1”
Robo will reboot once the command is received and the name is changed
You can use an instance of BLED112 to scan() and see all discoverable devices or simply check on your phone that the new ble name has been taken

my_robo.change_ble_name("Robo2")

Check Drive Action¶

check_drive_action(self)

returns the status of the drive action 1 = done, None = in progress, 0 = failed

if my_robo.check_drive_action():
        print "Drive Action Complete"

Check Turn Action¶

check_turn_action(self)

returns the status of the turn action 1 = done, None = in progress, 0 = failed

if my_robo.check_turn_action():
        print "Turn Action Complete"

Delay¶

delay(self, delay_time)

delay_time is the time in seconds to wait until function returns

my_robo.delay(1)

Display Text¶

display_text(self, text, matrices)

Cascaded diplay of text on one or more LED Matices

text is a string to be displayed on the matrices
matrices is a list of Matrix objects that should participate in the text display

my_robo.display_text("Welcome to Robo Wunderkind", [my_robo.Matrix1, my_robo.Matrix2, my_robo.Matrix3])

Drive¶

drive(self, vel, distance, direction, wait=1, motors=(1, 2), wd=89)

drive is Robo’s simplified command to have Robo drive a certain distance assuming a 2 motor configuration

vel is the desired velocity from 0-100%
distance is how far in centimeters Robo should drive
direction will detirmine forward or backward
wait is a flag that indicates if we wait in the function until the action is complete. set wait = 0 if we want to exit the function while driving
motors is a tuple of the two motors used to drive Robo
wd is the diameter of the wheels used, default is 89mm or 0x59mm in hex.
If you choose to change the wheels be sure to pass in the new wheel diameter

my_robo.drive(80, 30, 1)

Drive Forever¶

drive_inf(self, vel, direction)

vel is the desired velocity from 0-100%
direction will detirmine forward or backward

my_robo.drive_inf(80, 1)

Turn Forever¶

turn_inf(self, vel, direction)

vel is the desired velocity from 0-100%
direction will detirmine forward or backward

my_robo.turn_inf(80, 1)

Firmware Version¶

firmware(self)

Returns the firmware version of Robo

my_robo.firmware()

Get Robo Build¶

get_build(self)

returns a list of Robo Wunderkind moduels that are currently attached
The is updated automatically upon initialization of Robo object as well as when there has been a change in the build
The latest build is stored in self.build -> my_robo.build

build = my_robo.get_build()

Get BLE Characteristics¶

get_characteristics(self)

characteristics = my_robo.get_characteristics()
returns a list of GATT characteristics

characteristics = my_robo.get_characteristics()

Get RSSI¶

get_rssi(self)

rssi = my_robo.get_rssi()
returns the BLE signal strength rssi value

signal_strength = my_robo.get_rssi()

Set Drive Command¶

set_drive(self, motor_cmds, vel, distance, action_id, wd=0x59)

set_drive is Robo’s generic command to set the velocity and distance commands to multiple motors at once

motor_cmds is a list of motor objects folloed by the direction that motor should spin: [[1,0],[2,1],[3,0],[4,1]] motors from 1-6 are valid if connected
vel is the desired velocity from 0-100%
distance is the desired distance to travel in centimeters
action_id is a unique identifier that is sent back once Robo has completed the action. Use the self.drive_id by default, use check_drive_action() to know when it is done
wd is the diameter of the wheels used, default is 89mm or 0x59mm in hex. If you choose to change the wheels be sure to pass in the new wheel diameter

my_robo.set_drive([[1,0],[2,1],[3,0],[4,1]], 50, 100, my_robo.drive_id)

Sound Playback¶

sound(self, sound)

Plays the desired sound clip on the system cube speaker 0-7 are valid

my_robo.sound(0)

Stop¶

stop(self)

stops all motors from moving

my_robo.stop()

Stop All Actions¶

stop_all(self)

stops all outputs

my_robo.stop_all()

Turn¶

turn(self, vel, angle, direction, wait=1, motors=(1, 2), wd=89, turning_radius=91)

turn is Robo’s simplified command to have Robo turn a number of degrees assuming a 2 motor configuration

vel is the desired velocity from 0-100%
angle is the amount to have Robo turn in degrees
direction will detirmine clockwise or counter clockwise rotation
wait is a flag that indicates if we wait in the function until the turn is complete. set wait = 0 if we want to exit the function while turning
motors is a tuple of the two motors used to turn Robo
wd is the diameter of the wheels used, default is 89mm or 0x59mm in hex. If you choose to change the wheels be sure to pass in the new wheel diameter
turning_radius is the distance from the wheel to the centre of Robo’s turning axle in millimeters

my_robo.turn(40, 90, 1)

BLED112¶

Create BLED112 Instance

BLE = BLED112(com_port=None)

Connect to Device¶

connect_ble(self, name)

Connects to the BLE device with the name passed into the function if it exists

BLE.connect_ble("Robo")

Scan¶

scan(self)

Scans for nearby BLE devices and returns a list of dictionaries containing BLE device data

BLE.scan()

Start¶

start(self)

Starts the BLE dongle

BLE.start()

Stop¶

start(self)

Starts the BLE dongle

BLE.start()

Accelerometer¶

Get Sensor Values¶

get_values(self)

Returns a dictionary of all three acceleration values in gravitational units and all three gyro values as degrees per second

values = Robo.IMU1.get_values()

Button¶

Get Button State¶

get_state(self)

Returns the current state of the button

state = Robo.Button1.get_state()

Set Button Trigger¶

set_trigger(self, comparitor)

comparitor 0 sets pressed, -1 sets released, 1-254 defines the number of clicks before triggered

Robo.Button1.set_trigger(5) # sets the trigger for 5 clicks

Check Button Trigger¶

check_trigger(self)

Returns 1 if the trigger has happened

while not Robo.Button1.check_trigger():
        # do stuff

Display¶

Pre-Programmed Image¶

image(self, image_num, orientation, delay)

image_num is the index of the pre-programmed image 0-4
orientation is the desired orientation to display the image. 0 - 3 -> 0 - 270 degrees
delay is the time in milliseconds that the image will be displayed for 0->65535
Displays the pre-programmed image_num on the LED Display cube

Robo.Display1.image(0, 2, 1000)

Custom Image¶

custom_image(self, image, orientation, delay)

image is a 32 element array of 8-bit numbers representing the 16 rows of the desired image.
orientation is the desired orientation to display the image. 0 - 3 -> 0 - 270 degrees
delay is the time in milliseconds that the image will be displayed for 0->65535
Displays the given image on the LED Display cube

Robo_Logo = [0xff, 0xfc, 0xff, 0xfe, 0xef, 0xf7, 0xc7, 0xe3, 0xc4, 0x23, 0xee, 0x77, 0xff, 0xfe, 0xff, 0xfc, 0x00, 0x00, 0xfe, 0x3c, 0xfe, 0x7e, 0xfe, 0xff, 0xfe, 0xff, 0xfe, 0xff, 0xfe, 0x7e, 0xfe, 0x3c ]

Robo.Display1.custom_image(Robo_Logo, 1, 1000)

Pre-Programmed Animation¶

animate(self, animation_num, repeats, reverse, orientation)

animation_num is the index of the pre-programmed animation 0-2
repeats number of times to repeat the animation
reverse 0 or 1 to indicate if the animation should play forwards then backwards or just forwards
orientation is the desired orientation to display the image. 0 - 3 -> 0 - 270 degrees
delay is the time in milliseconds that the image will be displayed 0->65535
Displays the pre-programmed animation_num on the LED Display cube

Robo.Display1.animate(0, 5, 1, 0)

Custom Animation¶

custom_animation(self, animation, repeats, reverse, orientation, frame_rate)

animation is a list of images: 32 element arrays of 8-bit numbers representing the 16 rows of the desired images.
repeats number of times to repeat the animation
reverse 0 or 1 to indicate if the animation should play forwards then backwards or just forwards
orientation is the desired orientation to display the image. 0 - 3 -> 0 - 270 degrees
frame_rate is the time in milliseconds that the image frame will be displayed 0->65535
Displays the given animation on the LED Display cube

Robo_Logo = [0xff, 0xfc, 0xff, 0xfe, 0xef, 0xf7, 0xc7, 0xe3, 0xc4, 0x23, 0xee, 0x77, 0xff, 0xfe, 0xff, 0xfc, 0x00, 0x00, 0xfe, 0x3c, 0xfe, 0x7e, 0xfe, 0xff, 0xfe, 0xff, 0xfe, 0xff, 0xfe, 0x7e, 0xfe, 0x3c ]
One = [0x07, 0xc0, 0x0f, 0xc0, 0x1d, 0xc0, 0x19, 0xc0, 0x01, 0xc0, 0x01, 0xc0, 0x01, 0xc0, 0x01, 0xc0, 0x01, 0xc0, 0x01, 0xc0, 0x01, 0xc0, 0x01, 0xc0, 0x01, 0xc0, 0x1f, 0xfc, 0x1f, 0xfc, 0x1f, 0xfc]
Two = [0x07, 0x80, 0x0f, 0xc0, 0x1c, 0xe0, 0x18, 0x70, 0x18, 0x30, 0x00, 0x30, 0x00, 0x30, 0x00, 0x30, 0x00, 0x30, 0x00, 0x70, 0x00, 0x70, 0x00, 0xf0, 0x03, 0xc0, 0x07, 0xc0, 0x0f, 0xfc, 0x0f, 0xfc]
Three = [0x0f, 0xfe, 0x0f, 0xfe, 0x0f, 0x1e, 0x0e, 0x0e, 0x00, 0x0e, 0x00, 0x0e, 0x00, 0x0e, 0x00, 0xfe, 0x00, 0xfe, 0x00, 0xfe, 0x00, 0x0e, 0x00, 0x0e, 0x0e, 0x0e, 0x0f, 0x1e, 0x0f, 0xfe, 0x0f, 0xfe]

animation = [Robo_Logo, One, Two, Three]

Robo.Display1.custom_animation(animation, 1, 0, 0, 1000)

Reset¶

reset(self)

Clears and resets the LED Display cube

Robo.Display1.reset()

Light Sensor¶

Get Light Value¶

get_light(self)

Returns the light value in lx of the specified light cube

light = Robo.Light1.get_light()

Set Light Trigger¶

set_trigger(self, value, comparitor)

value is the lx value you want to se the trigger to
comparitor 0 is less than, 1 is greater than the set value

Robo.Light1.set_trigger(500, 0)

Check Light Trigger¶

check_trigger(self)

Returns 1 if the trigger has happened

while not Robo.Light1.check_trigger():
        # do stuff

Line Tracker LT¶

Get Sensor Values¶

get_sensor_values(self)

Returns a list of all three values of the lintracker IR sensors
[left, center, right]

values = Robo.LT1.get_sensor_values()

Get Right Value¶

get_right_value(self)

Returns the lintracker’s right IR sensor value

value = Robo.LT1.get_right_value()

Get Center Value¶

get_center_value(self)

Returns the lintracker’s center IR sensor value

value = Robo.LT1.get_center_value()

Get Left Value¶

get_left_value(self)

Returns the lintracker’s left IR sensor value

value = Robo.LT1.get_left_value()

Track Line¶

track(self,``direction``,``speed``)
direction must be 0 or 1 to indicate forwards or backwards
speed must be between 0 and 100%

Robo.LT1.track(0,75)

Check Line Tracker Action¶

check_action(self)

Returns 1 if the action is completed

while not Robo.LT1.check_action():
        # do stuff

LED Matrix¶

Display¶

set_display(self, rows)

rows is an 8 element array of 8-bit strings.
Displays the given rows on the specified LED Matrix

rows = ['00000000',
        '11000011',
        '11000011',
        '00000000',
        '10000001',
        '11000011',
        '00111100',
        '00000000'
       ],

Robo.Matrix1.set_display(rows)

Timed Display¶

set_display(self, rows, duration)

rows is an 8 element array of 8-bit strings.
duration is the time in seconds
Displays the given rows on the specified LED Matrix for the specified amount of time

rows = ['00000000',
        '11000011',
        '11000011',
        '00000000',
        '10000001',
        '11000011',
        '00111100',
        '00000000'
       ],

Robo.Matrix1.set_display(rows, 4)

Off¶

off(self)

Turns off the LED Matrix

Robo.Matrix1.off()

Check Action¶

check_action(self)

Returns 1 if the the action has completed

while not Robo.Matrix1.check_action():
        # do stuff while the timed display is on

Rotate Right¶

rotate_right(self, rows)

Rotates the image to the right by 90 degrees

image = Robo.Matrix1.rotate_right(rows)

Rotate Left¶

rotate_left(self, rows)

Rotates the image to the left by 90 degrees

image = Robo.Matrix1.rotate_left(rows)

Flip X¶

flip_x(self, rows)

Flips the image in the X axis

image = Robo.Matrix1.flip_x(rows)

Flip Y¶

flip_y(self, rows)

Flips the image in the Y axis

image = Robo.Matrix1.flip_y(rows)

Motion Sensor PIR¶

Get Motion State¶

get_state(self)

Returns the current state of the PIR

state = Robo.Motion1.get_state()

Set Motion Trigger¶

set_trigger(self, comparitor)

comparitor 0 sets no motion, 1 sets motion

Robo.Motion1.set_trigger(1) # sets the trigger to set off with motion

Check Motion Trigger¶

check_trigger(self)

Returns 1 if the trigger has happened

while not Robo.Motion1.check_trigger():
        # do stuff

Motor¶

Set PWM¶

set_pwm(self, pwm)

pwm must be between 0 and 255; where 127 = 100% CW and 129 = 100% CCW
0-100% CW -> 0-127 pwm 0-100% CCW -> 255-129
Sets a constant torque PWM signal to the motor

Robo.Motor1.set_pwm(60)

Spin Distance¶

spin_distance(self, vel, distance, wd=89)

vel must be between 0 and 100%
distance must be an integer in centimeters
wd is the wheel diameter and is by default 89 mm, the diameter of the large wheel.
If different wheels are attached please specify the diameter in mm

Robo will spin the motor at a constant velocity for the specified distance. If resistance is applied the motor will increase torque to try and maintain the velocity.
When approaching the end distance the motor slows down to ensure it covers the specified distance and does not overshoot

Robo.Motor1.set_distance(60, 80)

Spin Velocity¶

spin_velocity(self, vel)

vel must be between 0 and 100%

Robo will spin the motor at a constant velocity. If resistance is applied the motor will increase torque to try and maintain the velocity.

Robo.Motor1.set_velocity(60)

Stop¶

stop(self)

Stops the motor

Robo.Motor1.stop()

Check Motor Action¶

check_action(self)

Returns 1 if the action is completed

while not Robo.Motor1.check_action():
        # do stuff

RGB LED¶

Set Colour¶

set_rgb(self, red, green, blue)

Sets the RGB to the desired colour using a combination of red, green blue colour intensities

red 0-255 value for the red colour intensity
green 0-255 value for the green colour intensity
blue 0-255 value for the blue colour intensity

Robo.RGB1.set_rgb(120,25,255)

Blink RGB¶

blink_rgb(self, red, green, blue, num_blinks,``period`` )

red 0-255 value for the red colour intensity
green 0-255 value for the green colour intensity
blue 0-255 value for the blue colour intensity
num_blinks number of blinks
period period in milliseconds

Robo.RGB1.blink_rgb(255, 255, 255, 5, 1000)     # blink white 5 times

Timed RGB¶

timed_rgb(self, red, green, blue, time )

red 0-255 value for the red colour intensity
green 0-255 value for the green colour intensity
blue 0-255 value for the blue colour intensity
time LED on time in seconds

Robo.RGB1.timed_rgb(255, 255, 255, 2)   # white light for 2 seconds

Off¶

off(self)

Turns off the LED

Robo.RGB1.off()

Red¶

red(self)

Turns the LED Red

Robo.RGB1.red()

Green¶

green(self)

Turns the LED Green

Robo.RGB1.green()

Blue¶

blue(self)

Turns the LED Blue

Robo.RGB1.blue()

Yellow¶

yellow(self)

Turns the LED Yellow

Robo.RGB1.yellow()

Orange¶

orange(self)

Turns the LED Orange

Robo.RGB1.orange()

White¶

white(self)

Turns the LED White

Robo.RGB1.white()

Random Colour¶

random(self)

Shows a random colour on the LED

Robo.RGB1.random()

Check LED Action¶

check_action(self)

Returns 1 if the action is completed

while not Robo.RGB1.check_action():
        # do stuff

Servo¶

Set Angle¶

set_angle(self, angle)

angle must be between 0 and 255

Sets the servo to be positioned at the desired angle

Robo.Motor1.set_angle(90)

Check Servo Action¶

check_action(self)

Returns 1 if the action is completed

while not Robo.Servo1.check_action():
        # do stuff

Ultrasonic Sensor¶

Get Distance¶

get_distance(self)

Returns the current distance

distance = Robo.Ultrasonic1.get_distance()

Get Sound Level¶

get_sound_level(self)

Returns the current sound level

sound = Robo.Ultrasonic1.get_sound()

Set Distance Trigger¶

set_trigger(self, value,``comparitor``)

value is the trigger value in centimeters
comparitor 0 sets less than, 1 sets greater than value

Robo.Ultrasonic1.set_trigger(50, 1)  # sets the trigger to set off when a distance greater than 50 cm is seen

Set Sound Trigger¶

set_sound_trigger(self, value,``comparitor``)

value is the trigger value
comparitor 0 sets less than, 1 sets greater than value

Robo.Ultrasonic1.set_sound_trigger(150, 1)  # sets the trigger to set off when the sound is greater than 150

Check Distance Trigger¶

check_distance_trigger(self)

Returns 1 if the trigger has happened

while not Robo.Ultrasonic1.check_distance_trigger():
        # do stuff

Check Sound Trigger¶

check_distance_trigger(self)

Returns 1 if the trigger has happened

while not Robo.Ultrasonic1.check_sound_trigger():
        # do stuff

Contributing¶

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions¶

Report Bugs¶

Report bugs at https://github.com/JonRobo/robopython/issues.

If you are reporting a bug, please include:

Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.

Fix Bugs¶

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.

Implement Features¶

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.

Write Documentation¶

robopython could always use more documentation, whether as part of the official robopython docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback¶

The best way to send feedback is to file an issue at https://github.com/JonRobo/robopython/issues.

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!¶

Ready to contribute? Here’s how to set up robopython for local development.

Fork the robopython repo on GitHub.

Clone your fork locally:

$ git clone git@github.com:your_name_here/robopython.git

Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:
```
$ mkvirtualenv robopython
$ cd robopython/
$ python setup.py develop
```
Create a branch for local development:
```
$ git checkout -b name-of-your-bugfix-or-feature
```
Now you can make your changes locally.
When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:
```
$ flake8 robopython tests
$ python setup.py test or py.test
$ tox
```
To get flake8 and tox, just pip install them into your virtualenv.

Commit your changes and push your branch to GitHub:

$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

Submit a pull request through the GitHub website.

Pull Request Guidelines¶

Before you submit a pull request, check that it meets these guidelines:

The pull request should include tests.
If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
The pull request should work for Python 2.7, 3.4, 3.5 and 3.6, and for PyPy. Check https://travis-ci.org/JonRobo/robopython/pull_requests and make sure that the tests pass for all supported Python versions.

Tips¶

To run a subset of tests:

$ python -m unittest tests.test_robopython

Deploying¶

A reminder for the maintainers on how to deploy. Make sure all your changes are committed (including an entry in HISTORY.rst). Then run:

$ bumpversion patch # possible: major / minor / patch
$ git push
$ git push --tags

Travis will then deploy to PyPI if tests pass.

Credits¶

Development Lead¶

Jonathan William Morley <jon@robowunderkind.com>

Contributors¶

None yet. Why not be the first?

History¶

0.1.0 (2018-11-06)¶

First release on PyPI.

0.4.3 (2019-01-16)¶

0.4.4 (2019-10-15)¶

0.4.5 (2019-10-18)¶

0.4.6 (2019-10-27)¶

0.4.7 (2019-11-13)¶

0.4.8 (2020-02-19)¶

0.5.0 (2020-03-04)¶

1.0.1 (2020-09-03)¶

1.0.2 (2020-09-17)¶

1.0.3 (2021-03-15)¶

1.0.4 (2021-03-17)¶

Latest release on PyPI.