These instructions require the Raspberry Pi to be connected to the internet in order to download the required software.

If you are using a Model A or Model A+ we recommend you use a USB hub and a WiFi dongle to perform the initial setup.

Setting up the Raspberry Pi

Since the Raspberry Pi is difficult to access inside the DiddyBorg, we recommend you setup SSH so you can login to the Raspberry Pi using a network cable.
To setup SSH access:

Enter the following command in a terminal: sudo raspi-config

Move down to option 8 Advanced Options and press ENTER

Move down to option A4 SSH and press ENTER

Make sure Enable is highlighted and press ENTER

Wait until the dialog says SSH is enabled, then press ENTER

Move right until Finish is highlighted, then press ENTER

You may also want to set your router to give the Raspberry Pi a known IP address (so you can login to it later).
Consult you router manual if you wish to do this.

Installing the PicoBorg Reverse

The DiddyBorg uses a PicoBorg Reverse to drive the motors.
We will connect the board later, for now we simply need to install the software to control it.

You may need to enable I2C first, to do this:

Enter the following command in a terminal: sudo raspi-config

Move down to option 8 Advanced Options and press ENTER

Move down to option A7 I2C and press ENTER

Make sure Yes is highlighted and press ENTER

When the dialog says I2C is enabled press ENTER

Make sure Yes is highlighted again and press ENTER

When the dialog says I2C will be loaded by default press ENTER

Move right until Finish is highlighted, then press ENTER

If the I2C option is not available simply proceed to the next step.

To run through the automatic installer just use this one line in a terminal:bash <(curl https://www.piborg.org/installer/install-picoborgrev.txt)
If you would prefer to manually run through the steps use the commands below:

We have some example scripts for controlling DiddyBorg setup and ready to run.

To run through the automatic installer just use this one line in a terminal:bash <(curl https://www.piborg.org/installer/install-diddyborg.txt)
If you would prefer to manually run through the steps use the commands below:

If you wish to use a gamepad / joystick to control DiddyBorg (such as a PS3 controller) you need the joystick software.
You can get this by running the following command:sudo apt-get -y install joystick

If you want to use the Raspberry Pi camera you will also need to install some additional software libraries.
Before setting up the software, turn the Raspberry Pi off and connect the camera to the Raspberry Pi.

After powering the Raspberry Pi you want to enable the camera functionality:

Enter the following command in a terminal: sudo raspi-config

Move down to option 5 Enable camera and press ENTER

Make right until Enable is highlighted and press ENTER

Move right until Finish is highlighted, then press ENTER

If asked if you would like to reboot, make sure Yes is highlighted, then press ENTER

Wait for the Raspberry Pi to restart

You can check the Raspberry Pi camera is attached and working by using the following command:raspistill -d
If the camera is working you should see the image from the camera on the monitor for a few seconds.
If it is not working or incorrectly connected you will get error messages instead.

Next we want to install the Python library for talking to the camera:sudo apt-get -y install python-picamera

Finally if we want to do image processing then we want the OpenCV libraries as well.
This is needed for the ball-chasing example.
This download is a bit larger and may take a while:sudo apt-get -y install libcv-dev libopencv-dev python-opencv

Before Assembling the DiddyBorg

Now we have all the code ready to go, there are a few things we want to do before assembling him.

If you plan to use SSH to talk to the Raspberry Pi once assembled check it works before assembly

If you are using a joystick to control DiddyBorg, attach it to the Raspberry Pi and use jstest to check it works
See our JoyBorg script page for instructions on how to check this

If you want to use any of our examples check the settings (such as joystick button numbers) are correct, change them if necessary

The examples can be setup to run when the Raspberry Pi starts, find the script you want below for instructions on how to do this

If you wish to use any other devices (such as a WiFi dongle), now is the best time to set them up and make sure they work

Finally before assembling power the Raspberry Pi off and detach the camera

The Example Scripts

These are the example scripts for DiddyBorg.
They demonstrate how DiddyBorg can be used for both autonomous and manual control.
You can view the full source code here.

Simple movement - diddySequence.py

This script provides a simple example of moving DiddyBorg around in Python
It should move in a pattern which matches the following sequence:

Move in a square (~40 cm in size)

Move to the centre of the square in a single line

Spin around in both directions

Move back to the start as two separate lines

It does this by setting the motor power and waiting for lengths of time.
On different surfaces he will move quicker or slower, which means the settings may need adjusting for the surface.

This script is the best starting point for writing your own autonomous robot code from the examples available.
It is also the shortest and simplest of the examples.

Settings

These are the various settings in the script by line number:

32 timeForward1m: the number of seconds needed to move forward 1 meter
You can check this using test mode

33 timeSpin360: the number of seconds needed to spin a full 360°
You can check this using test mode

34 testMode: set to True to test the settings above, set to False to run the sequence instead

When using test mode you can check the settings are okay:

If the forward / backward drive goes too far, decrease timeForward1m

If the forward / backward drive does not go far enough, increase timeForward1m

If the left / right spin turns more than once, decrease timeSpin360

If the left / right spin turns less than once, increase timeSpin360

repeat until the values are roughly correct (it may not be possible to get them absolutely precise).

Run once

Go to the DiddyBorg code directory:cd ~/diddyborg
then run the script directly:./diddySequence.py

Run at startup

Make sure the script is not in test mode, otherwise it will not run!
Open crontab to make an addition using:crontab -e
this will open the scheduled task list in your default text editor (usually nano).

Add the following line to the bottom of the file:@reboot /home/pi/diddyborg/diddySequence.py
the script should now run whenever the Raspberry Pi is restarted / powered up.

Joystick control - diddyJoy.py

This script demonstrates how you can control DiddyBorg using a gamepad or joystick.The script requires the optional joystick setup to be completed.

You may wish to change which buttons on the gamepad / joystick perform which actions.
See our JoyBorg script page to work out which button numbers are which actual buttons, or see our PS3 controller page for the numbers if you plan on using a PS3 controller.

Settings

Joystick control settings:

43 axisUpDown: the axis index used for speed control

44 axisUpDownInverted: set to True if the robot runs the wrong way

45 axisLeftRight: the axis index used for steering control

46 axisLeftRightInverted: set to True if the robot turns the wrong way

47 buttonResetEpo: the button index used for resetting the safety stop, generally should not be needed

48 buttonSlow: the button index used for hold to drive slowly

49 slowFactor: the maximum drive speed when the hold to drive slowly button is held

50 buttonFastTurn: the button index used for hold to turn fast, allows turning on the spot whilst held

51 interval: the time between updates, smaller responds better, larger uses less processor time (conserve battery), the default of 0 means as fast as possible

44 voltageOut: the maximum voltage to run the motors at, the DiddyBorg motors are designed to run at 6v

Default PS3 buttons

The default values when using a PS3 controller correspond to:

Left stick up / down: Speed control

Right stick left / right: Steering control

L2: Drive slowly whilst held (limits to 50% speed)

R2: Turn fast whilst held (allows on the spot turning)

Start button: Resets the safety stop if tripped (indicated by script using the LED)

Run once

Go to the DiddyBorg code directory:cd ~/diddyborg
if you are using a PS3 controller and need to start the sixad process use the PS3 launcher:./ps3DiddyJoy.sh
otherwise run the script using the simple launcher:./runDiddyJoy.sh

Run at startup

Open crontab to make an addition using:crontab -e
this will open the scheduled task list in your default text editor (usually nano).

If you are using a PS3 controller add the following line to the bottom of the file:@reboot /home/pi/diddyborg/ps3DiddyJoy.sh
if you are not then add the following line instead:@reboot /home/pi/diddyborg/runDiddyJoy.sh
the script should now run whenever the Raspberry Pi is restarted / powered up.

Ball following - diddyFollowBall.py

This script demonstrates how DiddyBorg can become autonomous and run by himself.
We only use the Raspberry Pi camera in this example, but you could attach other sensors to perform other tasks.The script requires the optional camera setup to be completed.

57 voltageOut: the maximum voltage to run the motors at, the DiddyBorg motors are designed to run at 6v

Camera settings:

60 imageWidth: the width of the image to capture from the camera, larger takes longer to process

61 imageHeight: the height of the image to capture from the camera, larger takes longer to process

62 frameRate: the number of images to capture per second from the camera, too large and DiddyBorg will become slow to respond to changes in position

Auto drive settings:

65 autoMaxPower: the fastest DiddyBorg will move under automatic control, 1.0 represents the full power set by voltageOut

66 autoMinPower: the slowest DiddyBorg will move under automatic control (when not stopped), 0.2 represents 20% of the voltageOut setting

67 autoMinArea: the area which the target needs to occupy in the image before attempting to move towards it

68 autoMaxArea: the area which the target needs to occupy in the image before deciding DiddyBorg is close enough and stops moving

69 autoFullSpeedArea: the area which the target needs to occupy more than before DiddyBorg starts slowing down from autoMaxPower, set the same as autoMaxArea to not slow down at all

Run once

Go to the DiddyBorg code directory:cd ~/diddyborg
then run the script directly:./diddyFollowBall.py

Run at startup

Make sure the script is not in test mode, otherwise it will not run!
Open crontab to make an addition using:crontab -e
this will open the scheduled task list in your default text editor (usually nano).

Add the following line to the bottom of the file:@reboot /home/pi/diddyborg/diddyFollowBall.py
the script should now run whenever the Raspberry Pi is restarted / powered up.

Joystick control and ball following - diddyJoyBall.py

This script demonstrates how you can control DiddyBorg using a gamepad or joystick, but also how at the press of a button he can become autonomous and run by himself.
This is the most complex example in the list, it shows how automatic and manual control can be combined into a single piece of code.The script requires the optional joystick and camera setups to be completed.

You may wish to change which buttons on the gamepad / joystick perform which actions.
See our JoyBorg script page to work out which button numbers are which actual buttons, or see our PS3 controller page for the numbers if you plan on using a PS3 controller.

Settings

Joystick control settings:

61 axisUpDown: the axis index used for speed control

62 axisUpDownInverted: set to True if the robot runs the wrong way

63 axisLeftRight: the axis index used for steering control

64 axisLeftRightInverted: set to True if the robot turns the wrong way

65 buttonResetEpo: the button index used for resetting the safety stop, generally should not be needed

66 buttonSlow: the button index used for hold to drive slowly

67 slowFactor: the maximum drive speed when the hold to drive slowly button is held

68 buttonFastTurn: the button index used for hold to turn fast, allows turning on the spot whilst held

69 interval: the time between updates, smaller responds better, larger uses less processor time (conserve battery)

70 controllerLostLoops: the number of loops without any update from the controller before deciding it is out-of-range
This value is well-tuned for a Bluetooth attached PS3 controller, other controllers may want larger values (if the robot appears to stop at random increase this value)

71 buttonSetAutoMode: the button index used to enable automatic control

71 buttonSetManualMode: the button index used to enable manual control

76 voltageOut: the maximum voltage to run the motors at, the DiddyBorg motors are designed to run at 6v

Camera settings:

79 imageWidth: the width of the image to capture from the camera, larger takes longer to process

80 imageHeight: the height of the image to capture from the camera, larger takes longer to process

81 frameRate: the number of images to capture per second from the camera, too large and DiddyBorg will become slow to respond to changes in position

Auto drive settings:

84 autoMaxPower: the fastest DiddyBorg will move under automatic control, 1.0 represents full forward on the joystick

85 autoMinPower: the slowest DiddyBorg will move under automatic control (when not stopped), 0.2 represents 20% forward on the joystick

86 autoMinArea: the area which the target needs to occupy in the image before attempting to move towards it

87 autoMaxArea: the area which the target needs to occupy in the image before deciding DiddyBorg is close enough and stops moving

88 autoFullSpeedArea: the area which the target needs to occupy more than before DiddyBorg starts slowing down from autoMaxPower, set the same as autoMaxArea to not slow down at all

Default PS3 buttons

The default values when using a PS3 controller correspond to:

Left stick up / down: Speed control

Right stick left / right: Steering control

L2: Drive slowly whilst held (limits to 50% speed)

R2: Turn fast whilst held (allows on the spot turning)

Start button: Resets the safety stop if tripped (indicated by script using the LED)

D-Pad up: Switch to automatic control

D-Pad down: Switch to manual control

Run once

Go to the DiddyBorg code directory:cd ~/diddyborg
if you are using a PS3 controller and need to start the sixad process use the PS3 launcher:./ps3DiddyJoyBall.sh
otherwise run the script using the simple launcher:./runDiddyJoyBall.sh

Run at startup

Open crontab to make an addition using:crontab -e
this will open the scheduled task list in your default text editor (usually nano).

If you are using a PS3 controller add the following line to the bottom of the file:@reboot /home/pi/diddyborg/ps3DiddyJoyBall.sh
if you are not then add the following line instead:@reboot /home/pi/diddyborg/runDiddyJoyBall.sh
the script should now run whenever the Raspberry Pi is restarted / powered up.

Source Listings

Here is all the source code for the example scripts above, they are all included in the download made during installation.