A python and arduino control library for the EEZYbotARM 3d printed robot arm (Includes 3-D kinematics for Mk1 and Mk2)
A python and arduino controller for the EEZYbotARM Mk1 & Mk2 (Includes 3-D kinematics).
EEZYbotARMs are a range of four-axis, open source 3d-printable robot arms designed by Carlo Franciscone.
This code library provides functionality to control the EEZYbotARM (Mk1, Mk2) in 3-D space. Specifically its functionality includes:
==Important!== Please note this is a hobby robot arm. It should be used for learning projects only. I.e. don't expect it to pick up anything heavier than 5 grams (e.g. a glass marble).
The code library allows the user to easily map joint angles to an x,y,z co-ordinates, so that we know the position of the end effector
The mathematical calculations for the forward kinematics can be found here.
The code library allows the user to easily map x,y,z co-ordinates to joint angles, so that the EEZYbotARM can be controlled in 3-D space
The mathematical calculations for the inverse kinematics can be found here.
The code library allows the user to easily plot a (simulated) robot arm. It is easy to calculate and plot the robot arm workspace. As well as checking whether a cartesian (x,y,z) point is within or outside the workspace.
This code library is distributed with python and arduino components. The python code is responsible for high level kinematics calculations and simulation. The arduino code is responsbile for low level servo control.
This python code is distributed as a python package. A setup file is included and so dependent libraries should install with the package. :)
To install the package on Windows, OS X or Linux:
pip install -e .
This will create an editable install of the easyEZZYbotARM library
A future aim is to distribute this module using pip
To install the arduino code it is as simple as uploading the sketch 'arduino_sketches\easyEEZYbotARM_Arduino_Communication' to the arduino microcontroller.
The easiest way to do this is using the arduino IDE, see instructions at: https://www.arduino.cc/en/Main/Software
The arduino software uses ArminJo's ServoEasing library so that the motions of the servo motors are smooth and not sudden 'jolts'. Important: You must uncomment the line #define USE_PCA9685_SERVO_EXPANDER
in the file ServoEasing.h (as per the instructions for ServoEasing). The file ServoEasing.h can be found in the Arduino libraries directory.
This is the reference setup using the 'easyEZZYbotARM' repository. The servo motors represent the servo motors mounted on the EEZYbotARM. The PCA9685 is a widely available low cost board designed by Adafruit. The battery pack could be replaced by any DC power source < 6 volts.
This diagram is created using Fritzing. The Fritzing files can be found at '/fritzing_files'
Important: Please read the next Calibrating the EEZYbotARM section before you install servo motors into the robot arm.
For us to be able to control the robot arm, it's really important that the servo motors are installed in known 'reference positions' and that we understand how they behave. This is a two step process !
The servo motors (for angles q1, q2, q3) should be installed following the instructions below.
The aim of this installation procedure is to install the servo motors in a known reference position.
Please note: what is described in this sub-section is only currently implemented for the q1 servo motor in the easyEZZYbotARM library based on experimental values for a test robot. This is because it is strictly necessary for the q1 (base) servo motor. You can edit this for your particular motors (q2,q3) in the map_kinematicsToServoAngles
function in the easyEEZYbotARM python library. Doing so will improve the positional accuracy of the robot arm
Because the robot arm is using 'hobby servo motors', they don't always behave like we expect them to! For example, say we command a hobby servo (using pulse width modulation) to travel to an angle of 120 degrees, and then move to an angle of 70 degrees. If we measure these angles we are likely to find they are quite a way out! This makes a big difference to how the robot arm moves, so we need to correct any errors before we install the servo motors. An example of a setup to do this is shown in the video below
A reasonable way to do this is to command the servo motor to positions in increments of 10 degrees, and to measure the actual position of the motor. This can be recorded in a spreadsheet, so that we can map between a (demanded) input and an (actual) output using a linear function. An example of this (for the robot arm base servo motor) is given in this excel sheet. The graph produced from this is shown here.
A linear relationship can be estimated from this data (using excel line of best fit). The equation for this is displayed on the chart. You can see that this exact equation is implemented in the easyEEZYbotARM libary, this mapping between the (demanded) input and an (actual) output is implemented (for the q1 base servo motor) as follows:
# Calculate for q1
servoAngle_q1 = ((-2.0497)*q1) + 91.726 # from experimentation !
servoAngle_q1 = round(servoAngle_q1, 2)
I haven't experimented with lots of hobby servo motors, but I suspect that they are all a bit different in their performance between demanded value, and actual output. If your robot arm isn't quite in the right position (but almost is), then this could be something to optimise!
If you need help using this code libray, please in the first instance try googling your problem to see if you can find a solution. If that doesn't help then please do feel free to initiate a pull request on github.
Anyone is very welcome to contribute - please do. Below is a list of identified improvements.
Some useful best practice guidelines are here: https://opensource.guide/how-to-contribute/
Added information and resources on calibration and installation positions for the servo motors
Initial library version