4. 360pibot API

In this section the use of each module is documented. In the source code it is commented, if necessary, how each part of the code is working and what it is intended to do.

4.1. lib_scanner

Module for making measurements with a HC-SR04 [2] ultrasonic sensor and rotating it with a Parallax Standard Servo stand_data_sheet [4] .

This module includes three classes. One for making the measurements with an HC-SR04 [2] ultrasonic sensor lib_scanner.hcsr04, one for stearing a Parallax Standard Servo stand_data_sheet [4] lib_scanner.para_standard_servo and one which combines the first two to scan the surrounding lib_scanner.scanner .

class lib_scanner.hcsr04(pi, trigger, echo, pulse_len=15)[source]

Makes measurements with a HC-SR04 [2] ultrasonic sensor.

This class allows making measurements with a HC-SR04 [2] ultrasonic sensor. A trigger signal will be sent to a defined GPIO Pin trigger and a PWM will be recieved on a defined GPIO Pin echo. With the recieved PWM the distance to an object is calculated.

Parameters:
  • pi (pigpio.pi) – Instance of a pigpio.pi() object.
  • trigger (int) – GPIO identified by their Broadcom number, see elinux.org [1] . To this GPIO the trigger pin of the HC-SR04 [2] has to be connected.
  • echo (int) – GPIO identified by their Broadcom number, see elinux.org [1] . To this GPIO the echo pin of the HC-SR04 [2] has to be connected.
  • pulse_len (int,float) – Defines in microseconds the length of the pulse which is sent on the trigger GPIO. Default: 15, taken from the data sheet (10µs) and added 50%, to have a buffer to surely trigger the measurement.
cancel()[source]

Cancel the started callback function.

This method cancels the started callback function if initializing an object. As written in the pigpio callback [3] documentation, the callback function may be cancelled by calling the cancel function after the created instance is not needed anymore.

read(temp_air=20, upper_limit=4, number_of_sonic_bursts=8, added_buffer=2, debug=False)[source]

Measures the distance to an object.

This method triggers a measurement, does all the calculations and returns the distance in meters.

Parameters:
  • temp_air (int,float) – Temperature of the air in degree celsius. Default: 20.
  • upper_limit (int,float) – The upper measurement limit in meters. Default: 4, upper limit taken from the data sheet HC-SR04 [2] .
  • number_of_sonic_bursts (int) – The number of sonic bursts the sensor will make. Default: 8, taken from the data sheet HC-SR04 [2] .
  • added_buffer (int,float) – The added safety buffer for waiting for the distance measurement to complete. Default: 2, so 100% safety buffer.
  • debug (bool) – Controls if debugging printouts are made or not. For more details, have a look at the source code. Default: False, so no printouts are made.
Returns:

Measured distance in meters.
Return type:

float
class lib_scanner.para_standard_servo(pi, gpio, min_pw=1000, max_pw=2000, min_degree=-90, max_degree=90)[source]

Stears a servo, in this case a Parallax Standard Servo stand_data_sheet [4] .

This class stears a Parallax Standard Servo and should also work with other servos which have a 50Hz PWM for setting the position. The position of the Parallax Standard Servo can be set between -90 (min_degree) and +90 (max_degree) degree.

Note

min_pw and max_pw might needed to be interchanged, depending on if min_pw is moving the servo to max_right/clockwise or max_left/counter-clockwise, see methods max_left() and max_right(). max_right() -> min_pw should let the servo rotate clockwise.

Warning

Be carefull with setting the min and max pulsewidth! Test carefully min_pw and max_pw before setting them. Wrong values can damage the servo, see set_servo_pulsewidth [5] !!!

Parameters:
  • pi (pigpio.pi) – Instance of a pigpio.pi() object.
  • gpio (int) – GPIO identified by their Broadcom number, see elinux.org [1] . To this GPIO the signal wire of the servo has to be connected.
  • min_pw (int) – Min pulsewidth, see Warning, carefully test the value before! Default: 1000, taken from set_servo_pulsewidth [5] .
  • max_pw (int) – Max pulsewidth, see Warning, carefully test the value before! Default: 2000, taken from set_servo_pulsewidth [5] .
  • min_degree (int) – Min degree which the servo is able to move. Default: -90, taken from stand_data_sheet [4] .
  • max_degree (int) – Max degree which the servo is able to move. Default: +90, taken from stand_data_sheet [4] .
max_left()[source]

Sets the position of the servo to -90 degree, so min_degree (max left, counter-clockwise).

max_right()[source]

Sets the position of the servo to 90 degree, so max_degree (max right, clockwise).

middle_position()[source]

Sets the position of the servo to 0 degree, so middle position.

set_position(degree)[source]

Sets position of the servo in degree.

This method sets the servo position in degree. Minus is to the left, plus to the right.

Parameters:degree (int,float) – Should be between min_degree (max left) and max_degree (max right), otherwise the value will be limited to those values.
set_pw(pulse_width)[source]

Sets pulsewidth of the PWM.

This method allows setting the pulsewidth of the PWM directly. This can be used to test which min_pw and max_pw are appropriate. For this the min_pw and max_pw are needed to be set very small and very big, so that they do not limit the set pulsewidth. Normally they are used to protect the servo by limiting the pulsewidth to a certain range.

Warning

Be carefull with setting the min and max pulsewidth! Test carefully min_pw and max_pw before setting them. Wrong values can damage the servo, see set_servo_pulsewidth [5] !!!

Parameters:pulsewidth (int,float) – Pulsewidth of the PWM signal. Will be limited to min_pw and max_pw.
class lib_scanner.scanner(pi, trigger=6, echo=5, pulse_len=15, temp_air=20, upper_limit=4, number_of_sonic_bursts=8, added_buffer=2, gpio=22, min_pw=1000, max_pw=2000, min_degree=-90, max_degree=90, angles=[-90, -45, 0, 45, 90], time_servo_reach_position=3, debug=False)[source]

Scans the surrounding with the help of the hcsr04 and para_standard_servo classes.

This class stears the servo position and triggers measurements with the ultrasonic sensor. With a passed list, measurements will be made at the defined positions. A dict will be returned with the measured distances at the defined positions.

Warning

Be carefull with setting the min and max pulsewidth! Test carefully min_pw and max_pw before setting them. Wrong values can damage the servo, see set_servo_pulsewidth [5] !!!

Parameters:
  • pi (pigpio.pi) – Instance of a pigpio.pi() object.
  • trigger (int) – GPIO identified by their Broadcom number, see elinux.org [1] . To this GPIO the trigger pin of the HC-SR04 [2] has to be connected.
  • echo (int) – GPIO identified by their Broadcom number, see elinux.org [1] . To this GPIO the echo pin of the HC-SR04 [2] has to be connected.
  • pulse_len (int,float) – Defines in microseconds the length of the pulse, which is sent on the trigger GPIO. Default: 15, taken from the data sheet (10µs) and added 50%, to have a buffer to surely trigger the measurement.
  • temp_air (int,float) – Temperature of the air in degree celsius. Default: 20.
  • upper_limit (int,float) – The upper measurement limit in meters. Default: 4, upper limit taken from the data sheet HC-SR04 [2] .
  • number_of_sonic_bursts (int) – The number of sonic bursts the sensor will make. Default: 8, taken from the data sheet HC-SR04 [2] .
  • added_buffer (int,float) – The added safety buffer for waiting for the distance measurement. Default: 2, so 100% safety buffer.
  • gpio (int) – GPIO identified by their Broadcom number, see elinux.org [1] . To this GPIO the signal wire of the servo has to be connected.
  • min_pw (int) – Min pulsewidth, see Warning, carefully test the value before! Default: 1000, taken from set_servo_pulsewidth [5] .
  • max_pw (int) – Max pulsewidth, see Warning, carefully test the value before! Default: 2000, taken from set_servo_pulsewidth [5] .
  • min_degree (int) – Min degree which the servo is able to move. Default: -90, taken from stand_data_sheet [4] .
  • max_degree (int) – Max degree which the servo is able to move. Default: +90, taken from stand_data_sheet [4] .
  • angles (list) – List of positions where the servo moves to and the ultrasonic sensor will make measurements.
  • time_servo_reach_position (int,float) – Time in seconds to wait until the servo moves from one to another position. This needs to be tested for each servo. Default: 3, this should be sufficient to safely (incl. lot of safety buffer) reach each position before the measurement is made. If the servo is not oscillating after reaching each position, even a value of 0.35 was working fine with the demo implementation.
  • debug (bool) – Controls if debugging printouts and measurements are made or not. For more details, have a look at the source code. Default: False, so no printouts and measurements are made.
cancel()[source]

Cancel the started callback function.

This method cancels the started callback function if initializing an object. As written in the pigpio callback [3] documentation, the callback function may be cancelled by calling the cancel function after the created instance is not needed anymore.

read_all_angles()[source]

Moves servo and makes measurements at every defined position.

This method moves the servo to every position defined in list angles , makes a measurement there and afterwards returns a dict with the distance in meter for every position.

Returns:Measured distances in meters for each position defined in angles.
Return type:dict

4.2. lib_para_360_servo

Module for setting the speed and reading the position of a Parallax Feedback 360° High-Speed Servo 360_data_sheet [6] .

This module includes three classes. One for setting the speed lib_para_360_servo.write_pwm , one for reading the position lib_para_360_servo.read_pwm and one for calibrating a servo to determine the appropriate dcMin / dcMax values needed in lib_motion lib_para_360_servo.calibrate_pwm .

class lib_para_360_servo.calibrate_pwm(pi, gpio, measurement_time=120)[source]

Calibrates a Parallax Feedback 360° High-Speed Servo with the help of the read_pwm class.

This class helps to find out the min and max duty cycle of the feedback signal of a servo. This values ( dcMin / dcMax ) are then needed in lib_motion to have a more precise measurement of the position. The experience has shown that each servo has slightly different min/max duty cycle values, different than the once provided in the data sheet 360_data_sheet [6] . Values smaller and bigger than the printed out once as “duty_cycle_min/duty_cycle_max” are outliers and should therefore not be considered. This can be seen in the printouts of smallest/biggest 250 values. There are sometimes a few outliers. Compare the printouts of different runs to get a feeling for it.

Note

The robot wheels must be able to rotate free in the air for calibration. Rotating forward or backward might sometimes give slightly different results for min/max duty cycle. Choose the smallest value and the biggest value out of the forward and backward runs. Do both directions three times for each wheel, with speed = 0.2 and -0.2. Then chose the values. The speed has to be set manually, see Examples.

Parameters:
  • pi (pigpio.pi) – Instance of a pigpio.pi() object.
  • gpio (int) – GPIO identified by their Broadcom number, see elinux.org [1] . To this GPIO the feedback wire of the servo has to be connected.
  • measurement_time (int,float) – Time in seconds for how long duty cycle values will be collected, so for how long the measurement will be made. Default: 120.
Returns:

Printouts of different measurements

At the moment, the period for a 910 Hz signal is hardcoded, as in read_pwm() .

Todo

Enable the class to be able to handle different signals, not just 910 Hz.

class lib_para_360_servo.read_pwm(pi, gpio)[source]

Reads position of a Parallax Feedback 360° High-Speed Servo 360_data_sheet [6] .

This class reads the position of a Parallax Feedback 360° High-Speed Servo. At the moment, the period for a 910 Hz signal is hardcoded.

Parameters:
  • pi (pigpio.pi) – Instance of a pigpio.pi() object.
  • gpio (int) – GPIO identified by their Broadcom number, see elinux.org [1] . To this GPIO the feedback wire of the servo has to be connected.

Todo

Enable the class to be able to handle different signals, not just 910 Hz.

cancel()[source]

Cancel the started callback function.

This method cancels the started callback function if initializing an object. As written in the pigpio callback [3] documentation, the callback function may be cancelled by calling the cancel function after the created instance is not needed anymore.

read()[source]

Returns the recent measured duty cycle.

This method returns the recent measured duty cycle.

Returns:Recent measured duty cycle
Return type:float
class lib_para_360_servo.write_pwm(pi, gpio, min_pw=1280, max_pw=1720, min_speed=-1, max_speed=1)[source]

Steers a Parallax Feedback 360° High-Speed Servo 360_data_sheet [6] .

This class steers a Parallax Feedback 360° High-Speed Servo. Out of the speed range, defined by min_speed and max_speed, and the range of the pulsewidth, defined by min_pw and max_pw, the class allows setting the servo speed and automatically calculates the appropriate pulsewidth for the chosen speed value.

Note

min_pw and max_pw might needed to be interchanged, depending on if min_pw is moving the servo max_forward/clockwise or max_backwards/counter-clockwise, see methods max_forward() and max_backward(). max_forward() -> min_pw should let the servo rotate clockwise.

Warning

Be carefull with setting the min and max pulsewidth! Test carefully min_pw and max_pw before setting them. Wrong values can damage the servo, see set_servo_pulsewidth [5] !!!

Parameters:
  • pi (pigpio.pi) – Instance of a pigpio.pi() object.
  • gpio (int) – GPIO identified by their Broadcom number, see elinux.org [1] . To this GPIO the control wire of the servo has to be connected.
  • min_pw (int) – Min pulsewidth, see Warning, carefully test the value before! Default: 1280, taken from the data sheet 360_data_sheet [6] .
  • max_pw (int) – Max pulsewidth, see Warning, carefully test the value before! Default: 1720, taken from the data sheet 360_data_sheet [6] .
  • min_speed (int) – Min speed which the servo is able to move. Default: -1.
  • max_speed (int) – Max speed which the servo is able to move. Default: 1.
max_backward()[source]

Sets the speed of the servo to -1, so min_speed (max backwards, counter-clockwise)

max_forward()[source]

Sets the speed of the servo to 1, so max_speed (max forward, clockwise)

set_pw(pulse_width)[source]

Sets pulsewidth of the PWM.

This method allows setting the pulsewidth of the PWM directly. This can be used to test which min_pw and max_pw are appropriate. For this the min_pw and max_pw are needed to be set very small and very big, so that they do not limit the set pulsewidth. Normally they are used to protect the servo by limiting the pulsewidth to a certain range.

Warning

Be carefull with setting the min and max pulsewidth! Test carefully min_pw and max_pw before setting them. Wrong values can damage the servo, see set_servo_pulsewidth [5] !!!

Parameters:pulsewidth (int,float) – Pulsewidth of the PWM signal. Will be limited to min_pw and max_pw.
set_speed(speed)[source]

Sets speed of the servo.

This method sets the servos rotation speed. The speed range is defined by by min_speed and max_speed .

Parameters:speed (int,float) – Should be between min_speed and max_speed , otherwise the value will be limited to those values.
stop()[source]

Sets the speed of the servo to 0.

4.3. lib_motion

Module for moving the robot.

This module includes the method lib_motion.control.move() which is the core of the movement controlling. The module imports lib_para_360_servo .

class lib_motion.control(pi, width_robot=102, diameter_wheels=66, unitsFC=360, dcMin_l=27.3, dcMax_l=969.15, dcMin_r=27.3, dcMax_r=978.25, l_wheel_gpio=16, r_wheel_gpio=20, servo_l_gpio=17, min_pw_l=1280, max_pw_l=1720, min_speed_l=-1, max_speed_l=1, servo_r_gpio=27, min_pw_r=1280, max_pw_r=1720, min_speed_r=-1, max_speed_r=1, sampling_time=0.01, Kp_p=0.1, Ki_p=0.1, Kd_p=0, Kp_s=0.5, Ki_s=0, Kd_s=0)[source]

Controls the robot movement.

This class controls the robots movement by controlling the two Parallax Feedback 360° High-Speed Servos 360_data_sheet [6] . The robots local coordinate system is defined in the following way. X-axis positive is straight forward, y-axis positive is perpendicular to the x-axis in the direction to the left wheel. The center (0/0) is where the middle of the robots chassi is cutting across a imaginary line through both wheels/servos. Angle phi is the displacement of the local coordinate system to the real world coordinate system. See Used local coordinate system for a picture of it.

Warning

Be carefull with setting the min and max pulsewidth! Test carefully min_pw and max_pw before setting them. Wrong values can damage the servo, see set_servo_pulsewidth [5] !!!

Parameters:
  • pi (pigpio.pi) – Instance of a pigpio.pi() object.
  • width_robot (int) – Width of the robot in mm, so distance between middle right wheel and middle left wheel. Default: 102 mm, measured.
  • diameter_wheels – Diameter of both wheels. Default: 66 mm, measured and taken from the products website wheel_robot [7] .
  • unitsFC (int) – Units in a full circle, so each wheel is divided into X sections/ticks. This value should not be changed. Default: 360
  • dcMin_l (float) – Min duty cycle of the left wheel. Default: 27.3, measured with method lib_para_360_servo.calibrate_pwm() , see Examples .
  • dcMax_l (float) – Max duty cycle of the left wheel. Default: 969.15, measured with method lib_para_360_servo.calibrate_pwm() , see Examples .
  • dcMin_r (float) – Min duty cycle of the right wheel. Default: 27.3, measured with method lib_para_360_servo.calibrate_pwm() , see Examples .
  • dcMax_r (float) – Max duty cycle of the left wheel. Default: 978.25, measured with method lib_para_360_servo.calibrate_pwm() , see Examples .
  • l_wheel_gpio (int) – GPIO identified by their Broadcom number, see elinux.org [1] . To this GPIO the feedback wire of the left servo has to be connected.
  • r_wheel_gpio (int) – GPIO identified by their Broadcom number, see elinux.org [1] . To this GPIO the feedback wire of the right servo has to be connected.
  • servo_l_gpio (int) – GPIO identified by their Broadcom number, see elinux.org [1] . To this GPIO the control wire of the left servo has to be connected.
  • min_pw_l (int) – Min pulsewidth, see Warning, carefully test the value before! Default: 1280, taken from the data sheet 360_data_sheet [6] .
  • max_pw_l (int) – Max pulsewidth, see Warning, carefully test the value before! Default: 1720, taken from the data sheet 360_data_sheet [6] .
  • min_speed_l (int) – Min speed which the servo is able to move. Default: -1, so that the speed range is also scaled between -1 and 1 as the output of the inner control loop.
  • max_speed_l (int) – Max speed which the servo is able to move. Default: 1, so that the speed range is also scaled between -1 and 1 as the output of the inner control loop.
  • servo_r_gpio (int) – GPIO identified by their Broadcom number, see elinux.org [1] . To this GPIO the control wire of the right servo has to be connected.
  • min_pw_r (int) – Min pulsewidth, see Warning, carefully test the value before! Default: 1280, taken from the data sheet 360_data_sheet [6] .
  • max_pw_r (int) – Max pulsewidth, see Warning, carefully test the value before! Default: 1720, taken from the data sheet 360_data_sheet [6] .
  • min_speed_r (int) – Min speed which the servo is able to move. Default: -1, so that the speed range is also scaled between -1 and 1 as the output of the inner control loop.
  • max_speed_r (int) – Max speed which the servo is able to move. Default: 1, so that the speed range is also scaled between -1 and 1 as the output of the inner control loop.
  • sampling_time (float) – Sampling time of the four PID controllers in seconds. Default: 0.01. 1. PWM of motor feedback is 910Hz (0,001098901 s), so position changes cannot be recognized faster than 1.1 ms. Therefore, it is not needed to run the outer control loop more often and update the speed values which have a 50 Hz (20ms) PWM. 2. Tests of the runtime of the code including the controller part have shown that writing the pulsewidth (pi.set_servo_pulsewidth()) in lib_para_360_servo.write_pwm.set_pw() is the bottleneck which drastically slows down the code by the factor ~400 (0,002 seconds vs 0,000005 seconds; runtime with vs without writing pulsewidth). 3. For recognizing the RPMs of the wheels 10ms is needed to have enough changes in the position. This was found out by testing. See method move() for more informations.
  • Kp_p (int,float) – Kp value of the outer PID controllers, see method move() for more informations. Default: 0.1.
  • Ki_p (int,float) – Ki value of the outer PID controllers, see method move() for more informations. Default: 0.1.
  • Kd_p (int,float) – Kd value of the outer PID controllers, see method move() for more informations. Default: 0.
  • Kp_s (int,float) – Kp value of the inner PID controllers, see method move() for more informations. Default: 0.5.
  • Ki_s (int,float) – Ki value of the inner PID controllers, see method move() for more informations. Default: 0.
  • Kd_s (int,float) – Kd value of the inner PID controllers, see method move() for more informations. Default: 0.
cancel()[source]

Cancel the started callback function.

This method cancels the started callback function if initializing an object. As written in the pigpio callback [3] documentation, the callback function may be cancelled by calling the cancel function after the created instance is not needed anymore.

move(number_ticks=0, straight=False, turn=False)[source]

Core of motion control.

This method controls the movement of the robot. It is called from lib_motion.control.turn() or lib_motion.control.straight() and is not ment to be called directly. Four digital PID controllers are used to make two cascade control loops, one cascade control loop for each wheel. Each cascade control loop has the same parameters (P/I/D parameters), so that both wheels are controlled in the same way. Chosen default: Outer control loop is a PI controller, inner control loop is a P controller. The outer loop is a position controller, the inner loop a speed controller. After both wheels have reached their set-point (position), the method waits one second before the movement is marked as finished. This ensures that overshoots/oscillations are possible and that both wheels can independently reach their set-point (position). The I part of each PID controller is limited to -1 and 1, so that the sum of the errors is not integrated till infinity which means to very high or low values which might cause problems. The output value of each inner PID controller is scaled between -1 and 1 and the output value of each outer PID controller is limited to -1 and 1. This ensures that no scaling factors are introduced in the P/I/D parameters and also that the output of each PID controller matches the speed range of the servos, defined in lib_para_360_servo.write_pwm.set_speed() . A sliding median window is used to filter out the noise in the rotation speed measurement (ticks/s) which is done indirectly by measuring the position of the servo. Also a deadband filter after the error calculation of the outer control loop is implemented. This adjustments help to make the controllers more stable, e.g. filter out outliers while calculating the rotation speed and therefore avoid high value changes/jumps or avoid oscillations after reaching the set-point (position). The sample time of the digital PID controllers can also be freely chosen and does not influence the P/I/D parameters, the rotation speed measurement or the time before the movement is marked as finished.

Parameters:
  • number_ticks (int,float) – Number of ticks the wheels have to move.
  • straight (bool) – True or False, if robot should move straight. Default: False.
  • turn (bool) – True or False, if robot should turn. Default: False.
straight(distance_in_mm)[source]

Moves the robot about x mm forward or backward.

This method moves the robot x mm forward or backward. Positive distance values move the robot forward (regarding the local x-axis), negative distance values backward (regarding the local x-axis), see picture in Used local coordinate system , where the local coordinate system of the robot is shown. This method calls lib_motion.control.move() which controls the movement of the robot.

Parameters:distance_in_mm (int,float) – Distance the robot has to move.
turn(degree)[source]

Turns the robot about x degree.

This method turns the robot x degree to the left or to the right. Positive degree values turn the robot to the left, negative degree values to the right, see picture in Used local coordinate system , where the local coordinate system of the robot is shown. This method calls lib_motion.control.move() which controls the movement of the robot.

Parameters:degree (int,float) – Degree the robot has to turn.