PUZZLE-BOT
User’s Manual
1
CONTENTS
What is Puzzle-Bot? ……………………………………………………………………………………………………………………. 4 General Specs……………………………………………………………………………………………………………………………5
Block diagram ……………………………………………………………………………………………………………………….. 6 How does it work?……………………………………………………………………………………………………………………… 7 On-Board Configuration…………………………………………………………………………………………………………. 7 External Computing Configuration …………………………………………………………………………………………. 8 Hardware ………………………………………………………………………………………………………………………………….. 9 Basic Hardware configuration…………………………………………………………………………………………………9 Brushless Motor Version ……………………………………………………………………………………………………….. 9 Brushed Motors Version………………………………………………………………………………………………………11 Getting Started (On Board Configuration)………………………………………………………………………………..14 IDE Setup ……………………………………………………………………………………………………………………………… 14 Arduino IDE Installation ……………………………………………………………………………………………………… 14 Arduino IDE Setup ……………………………………………………………………………………………………………… 16 Creating a Basic Program……………………………………………………………………………………………………..19 DC Brushed Motor Version…………………………………………………………………………………………………. 19 Brushless Motor Version ……………………………………………………………………………………………………… 21 Uploading the Program to Puzzle-Bot ………………………………………………………………………………… 23 Getting Started (External Computing Configuration)………………………………………………………………..25 Starting the Puzzle-Bot ………………………………………………………………………………………………………….. 25 Brushless Motor Version ……………………………………………………………………………………………………… 25 Brushed Motor Version ………………………………………………………………………………………………………. 25 Connecting to the Puzzle-Bot ……………………………………………………………………………………………….. 27 Basic Web Interface …………………………………………………………………………………………………………….. 28 Accessing the web Interface…………………………………………………………………………………………….. 28 Configuration File (YAML file)………………………………………………………………………………………………… 30 Access to the Parameter file……………………………………………………………………………………………… 30 Parameter Configuration File description ………………………………………………………………………….. 32 How to flash …………………………………………………………………………………………………………………………. 38
2
Windows …………………………………………………………………………………………………………………………… 38 MATLAB Robotic User Interface………………………………………………………………………………………………… 41 WiFi Communication………………………………………………………………………………………………………….41 Stand Alone Style (SA-MRUI) …………………………………………………………………………………………………. 42 Basic workflow of the Stand-Alone Programming Style……………………………………………………….42 Getting Started Stand Alone Style (SA-MRUI) …………………………………………………………………….. 45 Examples Stand-Alone Style (SA-MRUI)……………………………………………………………………………….47 Arduino Style (A-MRUI)………………………………………………………………………………………………………….. 53 Starting the MATLAB Robotic User Interface (MRUI)…………………………………………………………….55 Running a Program in the MATLAB Robotic User Interface………………………………………………….57 GUI Description …………………………………………………………………………………………………………………. 61 Example of a Basic Control Algorithm …………………………………………………………………………………… 65 Example Basic …………………………………………………………………………………………………………………… 67 Other Control Algorithm Examples……………………………………………………………………………………..68 Pinout Diagrams……………………………………………………………………………………………………………………….70 Assembly Manual Brushless Version ………………………………………………………………………………………….. 74 Assembly Manual Brushed DC Motor Version …………………………………………………………………………… 80 Appendix ………………………………………………………………………………………………………………………………… 86 Sensor and Actuator Datasheets ………………………………………………………………………………………….. 88 Puzzle-Bot Parameter File ……………………………………………………………………………………………………… 89 Notes ………………………………………………………………………………………………………………………………………. 92
3
WHAT IS PUZZLE-BOT?
WELCOME TO PUZZLEBOT! BEFORE YOU START MAKING ROBOTICS, YOU’LL NEED TO KNOW SOME BASIC FUNCTIONALITIES OF THE ROBOT.
Puzzle-Bot is a platform for robotics and control systems development and education.
Unlike other products, Puzzle-Bot has sufficient processing capacity to handle multiple advanced add-on components (e.g. different actuators and sensors such as sonar and line following sensors). This allows customers to use a consistent platform for their entire robotics learning journey – from starter kit tutorials all the way to professional prototyping.
The “brain” of Puzzle-Bot is the Development Board. The board acts as a robust computational node for Starter Kit components (e.g. motors) and a communication interface to external computers (laptops, phones, Raspberry Pi).
It is designed using off-the-shelf components with the aim of achieving the most accessible price point at high-volume production. The Puzzle-Bot Starter Kit contains all the essential components needed to quickly access meaningful robotics capabilities (i.e. a programmable, roaming robot) and provides a user-friendly platform for incorporating a wide range of advanced add-on feature-sets.
FIGURE 1 PUZZLEBOT BASIC CONFIGURATION.
PUZZLE BOT
User’s Manual
4
GENERAL SPECS
Puzzle-Bot comes in two versions, with the same expansion capabilities but different motor types.
• The first version comprises of Brushed DC motors alongside a motor driver for motor control.
• The second version contains brushless motors with a built-in motor driver.
**For more information regarding the microcontroller, actuators, and sensors, refer to the appendix.
5
BLOCK DIAGRAM
The Puzzle-Bot block diagram is composed as follows
FIGURE 2 BASIC BLOCK DIAGRAM
• The Basic Configuration of the robot comprises of two brushless or brushed motors (depending on the version), with two encoders (one per motor), a graphic display to show basic information regarding the status of the robot, a Li-ion rechargeable battery (protected), and pins to connect other sensors or actuators.
• Each motor has a driver embedded for controlling the speed using PWM signals.
• The microcontroller contains built in WIFI and Bluetooth communication.
• External computing units such as (Raspberry pi, Nvidia Jetson, CPU) can be connected to
the robot using WIFI or Serial communication.
• Extra sensors and actuators can be connected into the free pins of the microcontroller
(servomotors, IR reflectance sensors, sonars etc.).
6
HOW DOES IT WORK?
Puzzle-Bot has two main configuration options. Depending on how it is used, the user can select between the following configurations.
ON-BOARD CONFIGURATION
FIGURE 3 PUZZLE-BOT ON-BOARD CONFIGURATION CONTROL DIAGRAM
• The user uploads their programs directly to the microcontroller inside the Puzzle-Bot.
• Libraries for communication with the different sensors and actuators are provided by Manchester Robotics ltd. • More peripherals can be attached (e.g. screen, sonar, IR sensor etc.)
• Some basic control libraries are provided.
• More complex controllers can be developed.
7
EXTERNAL COMPUTING CONFIGURATION
• The robot is controlled form an external computing unit.
• The communication is done via WIFI, the connection is done as a normal hotspot.
• The internal firmware and libraries for communicating with the robot are provided by
Manchester Robotics.
• The firmware contains libraries for the basic configuration (motors, servomotor, encoders,
ultrasonic sensor, IR Reflectance sensor, screen, WIFI communication, etc.)
• The user has access to a basic web interface for testing by using any browser.
• MATLAB libraries for communicating with the sensors and actuators are provided by
Manchester Robotics ltd. MATLAB contains an interface for simulating the robot and its
capabilities. MATLAB interface does not require any extra libraries for working.
• LabVIEW libraries for communicating with the sensors and actuators are provided by Manchester Robotics ltd. LabVIEW interface also contains a simulator with the basic capabilities of the robot. LabVIEW interface does not require any additional libraries or
packages from a third party or National Instruments to work.
FIGURE 4 PUZZLE-BOT EXTERNAL COMPUTING CONFIGURATION CONTROL DIAGRAM
8
HARDWARE
BASIC HARDWARE CONFIGURATION
The basic hardware for configuration is divided in two versions depending on the motors used by
the Puzzle-bot. The mechanical and Control Unit diagrams for both versions (brushed DC motors and Brushless motors) are shown below.
BRUSHLESS MOTOR VERSION
The brushless motor version, as described before, consists of two brushless motors, one for each wheel, one Puzzle-bot Control Module (Bottom PCB), one 5V Power Bank, one Caster ball and all the required mechanical components (plastic bases, standoffs, screws and nuts) required for its assembly. The following Diagram shows the basic configuration for the Brushless Motor Version.
FIGURE 5 PUZZLE-BOT BRUSHLESS MOTOR VERSION
9
The Puzzle-Bot Control Unit in Figure 8, is based, as described before, on a ESP microcontroller from Espressif Systems. The control Unit is capable of driving three brushless motors, as well as providing different rated voltages 5V and 12 V respectively; GPIO are available for any user intended purposes, and it can be attached to an external (5 – 12 V) power supply.
FIGURE 6 PUZZLE-BOT CONTROL MODULE DIAGRAM TABLE 1 PUZZLE-BOT CONTROL UNIT DESCRIPTION
Main Switch ON/OFF
Main Switch of the Puzzle-Bot
LCD Screen
LCD screen for showing basic information about Puzzle-Bot, or user defined information.
Servo Connector 1,2
Special connectors for servo motors or sensors (user defined), refer to Pinout diagrams section.
GPIO
General Purpose Input Outputs, refer to pinout diagrams section.
Microcontroller Reset
Microcontroller reset button.
Microcontroller Enable
Microcontroller enable button.
Brushless Motor ON/OFF Switch
Security ON/OFF switch for the brushless motors.
M1, M2, M3 Brushless Motor Connector
Brushless motor connectors refer to pinout diagrams section.
Power Selector Switch
Power selector switch (External power supply / USB power supply)
External Power Supply
External power supply input connector.
Micro USB Connector
Programming/Power supply Micro-USB connector.
Power Supply Pins
Power Supply header pins, refer to pinout diagram section.
10
BRUSHED MOTORS VERSION
The brushed DC motor version, as described before, consists of two DC brushed motors, one for each wheel, one Puzzle-Bot Control Module (Bottom PCB), one Puzzle-Bot DC Motor Control Module, one 5V Power Bank, one caster ball and all the required mechanical components (plastic bases, standoffs, screws and nuts) required for its assembly. The following Diagram shows the basic configuration for the Brushed DC Motor Version.
FIGURE 7 PUZZLE-BOT DC BRUSHED MOTOR VERSION
11
The Puzzle-Bot Control Unit as seen below, is based, as described before, on a ESP microcontroller from Espressif Systems. The control Unit can drive three brushless motors, as well as providing different rated voltages 5V and 12 V respectively; GPIO are available for any user intended purposes, and it can be attached to an external (5 – 12 V) power supply.
FIGURE 8 PUZZLE-BOT CONTROL MODULE DIAGRAM
**For description about each component refer to Table 1 Puzzle-Bot Control Unit Description.
12
FIGURE 9 PUZZLE-BOT CONTROL MODULE, DC BRUSHED MOTOR DRIVER EXTENSION DIAGRAM (TOP PCB) TABLE 2 CONTROL MODULE, DC BRUSHED MOTOR DRIVER EXTENSION GENERAL DESCRIPTION
Servo Connector 1,2
Special connectors for servo motors or sensors (user defined), refer to Pinout diagrams section.
GPIO Extension (Reflectance Sensor)
General Purpose Input Output dedicated for easy access when using reflectance sensor (if included). Refer to Pinout diagrams section.
GPIO
General Purpose Input Output, refer to pinout diagrams section.
DC Brushed Motor Connector (Motor 1, Motor 2)
DC Brushed motor connectors refer to pinout diagrams section
Brushed DC Motor ON/OFF Switch
Security ON/OFF switch for the DC brushed motors.
13
GETTING STARTED (ON BOARD CONFIGURATION)
As described before, the user can directly upload the program to the ESP32 microcontroller. Some basic libraries for communicating with the different sensors and actuators incorporated in the Puzzle-Bot are provided by Manchester Robotics ltd. as well as the instruction to compile such libraries.
IDE SETUP
Although there exists a specific IDE software provided by Espressif Systems which can be used for programming the ESP32, Manchester Robotics ltd. recommends the usage of the Arduino IDE programming environment, for its easy to use user interface and the big community supporting it.
ARDUINO IDE INSTALLATION
In this section a basic tutorial on how to install Arduino IDE will be shown. These instructions are based in https://www.arduino.cc/en/Guide
1. Download the Arduino IDE software from https://www.arduino.cc/
FIGURE 10 ARDUINO IDE DOWNLOAD. **PLEASE NOTE THAT THE WEBPAGE CAN CHANGE
2. Select the operating system where to install the Arduino IDE (Manchester Robotics ltd. does not recommend using the Online IDE)
14
FIGURE 11 SELECT OPERATING SYSTEM AND START DOWNLOAD. **NOTE THAT THIS WEBPAGE CAN CHANGE
3. For each operating system, there is a different set of instructions that can be found in https://www.arduino.cc/en/Guide follow the instructions for the selected operating system accordingly.
FIGURE 12 DIFFERENT OPERATING SYSTEM INSTALLATION INSTRUCTIONS. **PLEASE NOTE THE WEBPAGE CAN CHANGE.
4. After the installation is finished, open the program if the installation was successful and the following screen should appear. Manchester Robotics ltd. recommends making some example tutorials and get use to the basics of the Arduino IDE by following the tutorials in https://www.arduino.cc/en/Guide.
15
FIGURE 13 ARDUINO IDE, MAIN SCREEN
ARDUINO IDE SETUP
To use the Arduino IDE to program the ESP32, the IDE must be set up before trying to upload any sketch into the microcontroller. The following set up is based on the Web tutorials found in
Installing the ESP32 Board in Arduino IDE (Windows, Mac OS X, Linux)
1. In your Arduino IDE, go to File> Preferences
FIGURE 14 ARDUINO IDE PREFERENCES
2. Enter https://dl.espressif.com/dl/package_esp32_index.json into the “Additional Board Manager URLs” field as shown in the figure below. Then, click the “OK” button.
16
FIGURE 15 ARDUINO IDE PREFERENCES
3. Open the Boards Manager. Go to Tools > Board > Boards Manager…
FIGURE 16 ARDUINO BOARD MANAGER
4. Search for ESP32 and press install button for the “ESP32 by Espressif Systems“.
17
FIGURE 17 ESP32 LIBRARY
5. That’s it. It should be installed after a few seconds.
FIGURE 18 ESP32 LIBRARY INSTALLED
6. For testing the installation follow the steps in https://randomnerdtutorials.com/installing-the-esp32-board-in-arduino-ide-windows- instructions/
18
CREATING A BASIC PROGRAM
In this section a basic program example for reading information from the motor encoders and sending different speeds into the motors will be shown using the motor and encoder libraries provided by Manchester Robotics ltd. As stated previously, Manchester Robotics ltd provides some basic libraries for controlling the different actuators and sensors included with the Puzzle-Bot, however the user can build their own libraries if necessary. For further information regarding the libraries visit the Manchester Robotics ltd. Git repository.
Note for further details on how to add libraries and compiling the software or further Arduino programming references, please refer to the Arduino Tutorials webpage https://www.arduino.cc/en/Tutorial/HomePage.
Note For datasheets corresponding to the Motors, Encoders, Servo Motor, Sonar and Reflectacne sensor, check the Appendix.
DC BRUSHED MOTOR VERSION
19
FIGURE 19 EXAMPLE CODE FOR DC BRUSHED MOTORS USING THE MOTOR AND ENCODER LIBRARIES PROVIDED BY MANCHESTER ROBOTICS LTD
20
BRUSHLESS MOTOR VERSION
21
FIGURE 20 EXAMPLE CODE FOR BRUSHLESS MOTORS USING THE MOTOR AND ENCODER LIBRARIES PROVIDED BY MANCHESTER ROBOTICS LTD
22
UPLOADING THE PROGRAM TO PUZZLE-BOT
To upload a program to the ESP32 microcontroller follow the next steps.
1. Connect the microUSB cable to the Puzzle-Bot Control Module. Make sure the Main Switch is ON and the Power Selector Switch is in USB mode. Note that the figure is only for illustrative purposes, you don’t have to detach the Control Module from the robot.
FIGURE 21 USB CONNECTION TO PUZZLE-BOT CONTROL MODULE
2. Select the ESP32 Dev Module from Tools>Board>ESP32 Dev Module
FIGURE 22 ESP32 BOARD SELECTION
23
3. Select the computer USB port (COM) where the Control Module is connected
FIGURE 23 USB PORT (COM) SELECTION
4. Upload the program to the Puzzle-Bot Control Module.
FIGURE 24 UPLOAD THE PROGRAM TO THE PUZZLE-BOT CONTROL MODULE
5. Wait until the program finish uploading.
FIGURE 25 PROGRAM DONE UPLOADING
24
GETTING STARTED (EXTERNAL COMPUTING CONFIGURATION)
In the following section a basic introduction on how to get started with the robot using the external computing configuration will be presented. Some basic functionalities, such as starting the Puzzle- Bot, connecting to the robot, basic testing and parameter configuration will be shown.
STARTING THE PUZZLE-BOT
BRUSHLESS MOTOR VERSION
1. Connect the Power Bank (if included) to the Micro USB connector or a regulated Power
Supply (Battery etc.) to the external Power supply connector.
2. Select the Power supply from the power selector switch (Battery/USB).
3. Turn ON the Brushless Motor Switch.
4. Turn ON the Main Switch.
5. Verify that the screen is displaying information as shown in Figure 28.*
FIGURE 26 PUZZLE-BOT BRUSHLESS MOTOR VERSION, SIDE VIEW (RIGHT, LEFT RESPECTIVELY)
BRUSHED MOTOR VERSION
1. Follow Steps 1 and 2 from the Brushless Motor Version.
2. Turn ON the DC Brushed Motors Switch in the Top PCB.
3. Turn ON the Main Switch.
4. Verify that the screen is displaying information as shown in Figure 28.*
FIGURE 27 PUZZLE-BOT DC BRUSHED MOTOR VERSION, SIDE VIEW (RIGHT, LEFT RESPECTIVELY)
25
FIGURE 28 INFORMATION DISPLAYED ON THE LCD SCREEN (SSID, IP AND PASSWORD MAY DIFFER DEPENDING ON THE CONFIGURATION).
*If not, flash the PCB according to the section How to flash.
26
CONNECTING TO THE PUZZLE-BOT
The following sections are used for the External Computing Unit Configuration, using the firmware binaries provided by Manchester Robotics ltd. Please note that all the robots come pre- programmed with such binaries unless the user modify the program (On Board Configuration). The original binaries can be flashed anytime by following the steps in the section (How to Flash).
1. Select the Network ( ) icon on the taskbar. The icon that appears depends on your current connection state. If you don’t see one of the network icons (or a similar one) shown in the following image, select the Up arrow ( ) to see if it appears there.
2. Choose the Puzzle-Bot Wi-Fi network of the robot you want (Puzzle-Bot x), then select Connect.
3. Type the network password as shown on the LCD Display, and then select Next.
FIGURE 29 LCD SCREEN INFORMATION
4. Once Connected the following figure in the Network Settings should appear.
FIGURE 30 SUCCESSFUL CONNECTION TO PUZZLE-BOT
27
BASIC WEB INTERFACE
The robot has a web interface when in external computing unit configuration; for testing the different sensors and actuators equipped in the robot. In this webpage the speeds of the motors can be set, to be tested and driven to a desired speed. The measured speed of the wheels will be shown on the interface, as well as the data from any sensors attached to the robot.
ACCESSING THE WEB INTERFACE
1. Open any web browser
FIGURE 31 WEB BROWSER EXAMPLES
2. Type in the search bar (address bar) the IP Address of the robot as displayed on the LCD screen in Figure 29.
FIGURE 32 ADDRESS BAR
3. The following webpage should appear.
FIGURE 33 ROBOT WEB INTERFACE
28
TABLE 3 WEB INTERFACE GENERAL DESCRIPTION
IP Address
IP address of the robot of control
Right/Left Motor Velocities*
Right/ Left wheel velocities display
Right/Left Motor Velocity Set Point
Set Point for the right and left wheel velocities.
Servo Motor Offset**
Offset of the servo motor
Servo Motor Angle Set Point**
Set Point for the servo motor angle
Sonar Distance***
Sonar distance display
Reflectance Sensor Calibration****
Initialise calibration of the reflectance sensor
Reflectance Sensor Reflective Values****
Values given by each reflectance sensor [S1,S2,…,SN].
Reflectance Sensor Line Position****
Position of the line after calibration with respect to the reflectance sensor centre.
*The wheels should run forward(toward to the sonar) when velocities are positive, if not, check Parameter Configuration File description and change the sign of encoder.
**For information regarding Servo Motor refer to the Appendix.
***For information about sonar refer to the Appendix.
****For Reflectance sensor information and calibration refer to the Appendix.
29
CONFIGURATION FILE (YAML FILE)
Puzzle-Bot contains a configuration file for defining the different working modes, controllers, sensor
and actuators. The configuration file is based on a YAML parameter file. To access and modify such configuration file follow steps shown in this section.
ACCESS TO THE PARAMETER FILE
1. Connect to the robot following the steps in Connecting to the Puzzle-Bot
2. Type in the address bar of web browser the IP address of the robot followed by “/config”
as shown in the following image.
FIGURE 34 ACCESS TO THE PUZZLE-BOT CONFIGURATION FILE
3. The following page should appear.
FIGURE 35 PARAMETER FILE (YAML)
4. Manchester Robotics ltd. facilitates the users previously defined parameter configuration files for both Brushless and Brushed DC motor Puzzle-Bot versions. They can be easily used by following the next steps.
I. Open the configuration webpage as defined in steps 1 to 3.
II. Download pre-defined parameter configuration files for the desired Puzzle-Bot
Version.
30
FIGURE 36 PRE-DEFINED PARAMETER CONFIGURATION FILES
III. Delete the current parameter on the webpage.
IV. Open the desired file and copy the parameters in the readme.
V. Paste the copied parameters file to the webpage shown in Figure 35.
VI. Press the “Upload to robot” button at the top of the webpage as shown in Figure
35.
VII. Restart the robot by turning it OFF and ON again from the main switch.
31
PARAMETER CONFIGURATION FILE DESCRIPTION
As stated before, when using the binaries provided by Manchester Robotics ltd, the robot can be configured to work in different modes and with different sensors and actuators. In the following sections the basic working modes that are configured in the parameter configuration file will be described.
MAIN PARAMETERS OF THE ROBOT
In this section of the parameter configuration file, the main parameters that describe the type of robot and its physical characteristics are described.
• The type of robot describes the robot to be used as differential drive robot(1) or a holonomic robot (2). Note, Puzzle-Bot is a differential drive robot.
• Changing this parameter (1,2 or 3) allows Puzzle-Bot to work with different control inputs depending on the user.
1. Robot Linear and Angular Velocities provide the linear 𝑣 and angular 𝜔 velocities to the robot as seen in Figure 37. The velocities are then converted in the firmware to wheel velocities and a PID controller in each wheel, makes the robot reach its set point (PID control parameters for each wheel can be re-tuned as explained in the following section).
FIGURE 37 ROBOT VELOCITIES
2. Wheel angular velocities, form the external computing unit, the robot receives as inputs the set points for each wheel angular velocities (𝜔𝑟,𝜔𝑙). As in the previous case, a PID controller, inside the firmware, is used to regulate the speed of each wheel. PID parameters can be re-tuned in the following section.
3. Wheel PWM voltage signals, this input mode receives a value between [-1, 1], from the external computing unit, for setting the wheel angular speed. The interval [-1,1] maps the duty cycle of the signal [0%, 100%]and the wheel rotation direction i.e. [−1,1] → [−100%, 100%], where -100% represents full power backwards and 100% full power forward. Note that this configuration does not run any controller in the firmware.
• Wheelbase and Wheel Radius represent the physical characteristics of the robot used for transforming the robot velocities (𝑣,𝜔) into wheel angular velocities (𝜔𝑟,𝜔𝑙). Wheelbase is half of the distance between wheels of the robot (robot width) and wheel radius is the radius of the wheels.
• Topic Vx, Vy, W, used for receiving linear and angular velocities from an external computing unit. Further information, refer to the advanced manual configuration.
32
TABLE 4 MAIN PARAMETERS OF THE ROBOT
Main parameters for the robot
Robot:
Type:
1
1-differential drive robot; 2-holonomic robot
ControlInput:
3
1-robot linear and angular velocities; 2-wheel angular velocities setpoints; 3- wheel PWM signals
WheelBase:
0.083
Half of the robot width
WheelRadius:
0.0505
Wheel radius
TopicVx:
VelocityLinearX
Topic for receiving linear velocity of the robot**
TopicVy:
VelocityLinearY
Topic for receiving linear velocity of the robot on Y(for holonomic robot)**
TopicW:
VelocityAngular
Topic for receiving angular velocity of the robot**
**For further information regarding topics for controlling the robot, refer to the advanced manual configuration (Advanced Users).
PARAMETERS OF THE WHEELS (LEFT AND RIGHT)
In this section of the parameter configuration file, the main parameters that describe the type of motors and encoders used for the right and left wheels and its physical parameters are described. For the purposes of simplicity only one table will be shown nonetheless please note that the parameters for the right and left motors are defined separately.
• Motor Pins, define the microcontroller pins used to connect the motor. For the Brushed version of the Puzzle-Bot, the pin vector represents [PWM, InA, InB] respectively. For the brushless motor version the pin vector represents [PWM, Dir], respectively. Refer to Pinout reference for further information.
• Motor Sign, motor rotation direction sign setting.
• Motor Type defines the type of motor to be used, i.e., brushed or brushless.
• Motor Topic defines the topic used for receiving the PWM signal. Further information, refer
to the advanced manual configuration.
• Encoder Pins, define microcontroller pins used to connect the encoders. For the Brushed
version of the Puzzle-Bot pin vector, represents [EncB, EncA], respectively, for the brushless motor version the pin vector represents [Enc, Dir], respectively. Refer to Pinout reference and motor datasheets for further information.
• Encoder Sign, define the encoder direction setting.
• Encoder Ticks, number of ticks from the encoder per rotation.
• Encoder Gear, define the gear ratio of the motor as 𝑥: 1 where 𝑥 is the input ratio.
• Encoder Type, define the type of encoder (1) single channel, (2) dual channel encoder.
Note Brushed motors contain a double channel encoder, brushless motors are single
channel.
• Encoder Measure Type, Define the way of measurement for the different type of encoders.
Dual channel, count pulses (2), Single channel, pulse duration (1).
• Encoder Topic, defines the topic used for publishing the velocity measured by the
encoders. Further information, refer to the advanced manual configuration.
33
• PID Kp, define the proportional gain for the left/right wheel PID controller.
• PID Ti, define the Integration time for the left/right wheel PID controller.
• PID Td, define the Derivation time for the left/right wheel PID controller.
• PID Dead Zone, define the dead zone symmetrical around zero, for the left/right wheel PID
controller.
• PID Topic, defines the topic used for receiving the velocity set point defined by the user.
Further information refer to the advanced manual configuration.
TABLE 5 CONFIGURATION PARAMETERS FOR THE LEFT/RIGHT WHEEL
Parameters for the right/left wheel
Right/Left Wheel:
Motor:
Right motor parameters
Pins:
[4, 15, 18]
Motor driver pins
Sign:
1
Motor direction setting (-1/1)
Type:
2
Motor type. 1-brushless; 2-brushed
Topic:
ControlR
Topic for receiving control pwm**
Encoder:
Right encoder parameters
Pins:
[36, 34]
Encoder pins
Sign:
-1
Encoder direction setting (-1/1)
Ticks:
48
Encoder number of ticks for one rotation
Gear:
34
Gear ratio
Type: 2
2
Encoder type. 1-single pulse(no direction); 2-double pulse(with direction)
MeasureType:
1
Encoder velocity measurement type. 1-count pulses; 2-measure pulse duration
Topic:
VelocityEncR
Encoder velocity publish topic**
Pid:
Right Pid controller parameters
Kp:
0.1
Proportional gain
Ti:
0.05
Integration time
Td:
0
Derivation time
DeadZone:
0.1
Motor control dead zone
Topic:
VelocitySetR
Topic for receiving velocity setpoint**
**For further information regarding topics for controlling the robot, refer to the advanced manual configuration (Advanced Users).
NETWORK PARAMETERS
In this section of the parameter configuration file, the main Network parameters are described.
• Nework SSID, Sets the Network name or “access point ID”, shown in the LCD display.
• Nework Password, Sets the Network Password, shown in the LCD display.
• Nework IP, Sets the IP of the Access Point, shown in the LCD display.
• Nework RosIP, Sets the IP for the ROS master, when ROS connectivity is enabled.
• Nework PortWeb, Sets the web server port.
34
• Nework PortData, Sets the Port for data communication server (tcp/udp).
• Nework WiFi Power, Sets the WiFi transmitting power in the ESP32.
• Nework WebPage, Sets the Domain name of the webpage.
TABLE 6 NETWORK CONFIGURATION PARAMETERS
Network parameters
Network:
SSID:
Puzzlebot1
Access point ssid
Password:
Puzzlebot72
Access point password
IP:
[192, 168, 1, 1]
Access point IP
RosIP:
[192, 168, 1, 2]
Ros master IP (when ros connection is active)**
PortWeb:
80
Port for the web server**
PortData:
3141
Port for data communication server (tcp/udp) **
WiFiPower:
78
Wifi transmitter power (78 is maximum)
WebPage:
puzzlebot
Domain name for the webpage
**For further information regarding server configuration and ROS connectivity for controlling the robot, refer to the advanced manual configuration (Advanced Users).
ACTIVE MODULES CONFIGURATION
In this section of the parameter configuration file, the active module configuration will be described. Active modules refer to the modules that come pre-programmed by Manchester Robotics ltd. in the Puzzle-Bot, these can be activated or deactivated if the modules are included in the Puzzle-Bot system.
• Active Modules: Servo Motor, Sonar, Reflectance Sensor, Screen, ROS, Activate the modules by setting a 1 for activating and a 0 for deactivating the modules in Puzzle-Bot.
TABLE 7 ACTIVE MODULES CONFIGURATION
**For further information regarding ROS connectivity for controlling the robot, refer to the advanced manual configuration (Advanced Users).
SENSOR AND ACTUATOR CONFIGURATION
In this section the parameter configuration for the Sonar, Servo Motor and Reflectance sensor (if included), will be described.
• Sonar Pins, Input pin of the sonar, refer to pinout diagram section.
Active modules settings
ActiveModules:
Servo:
1
Servo motor on/off (1/0)
Sonar:
1
Sonar on/off (1/0)
Reflect:
1
Reflectance sensorr on/off (1/0)
Screen:
1
Screen on/off (1/0)
Ros:
0
Ros communication on/off (1/0)**
35
• Sonar Topic, define the Topic for publishing sonar measured distance. For further information, refer to the advanced manual configuration.
• Servo Pins, define the Servo motor pin.
• Servo Offset, define the Servo offset from the center.
• Servo Topic, defines the topic used for receiving the servo motor angle set point (deg)
defined by the user. For further information, refer to the advanced manual configuration.
• Reflectance NPins, Define the number of reflectance sensors used.
• Reflectance Pins, Define Reflectance sensor input pins in the Puzzle-Bot Control Unit
[S1, S2,…, SNPins].
• Reflectance EmitterPins, define the emitter pins of the reflectance sensor, refer to the
datasheet of the reflectance sensor and the Pinout diagram section.
• Reflectance EmitterSelect, select the odd (1), even (2) or all (3) emitters of the reflectance
sensor.
• Reflectance MinValues, define the Minimal reflectance values measured during
calibration (use webpage).
• Reflectance MinAvg, set the minimal reflectance average value measured during
calibration
• Reflectance Threshold, line detection threshold.
• Reflectance Topic, set the topic used for publishing the line position when using the
reflectance sensor, with respect to the center of the sensor. Further information, refer to the advanced manual configuration.
TABLE 8 SENSOR AND ACTUATOR CONFIGURATION
Parameters for sonar
Sonar:
Pins:
14
Sonar pins
Topic:
SonarDistance
Topic for publishing sonar measured distance**
Parameters for servo motor
Servo:
Pins:
5
Servo motor pins
Offset:
0
Servo motor center offset
Topic:
ServoAngle
Topic for receiving servo motor angle (degrees)**
Parameters for reflectance sensor
Reflectance:
NPins:
6
Number of pins (number of light sensors used)
Pins:
[32, 25, 27, 19, 23, 22]
Reflectance pins
EmitterPins:
[13, 12]
Emitter pins (for selecting even/odd lights on/off)
EmitterSelect:
2
Emitter selector. 1-even; 2-odd; 3-all
36
MinValues:
[600, 600, 600, 600, 600, 600]
Minimal reflectance values measured during calibration (use webpage)
MinAvg:
2000
Minimal reflectance average value measured during calibration
Threshold:
1.1
Line detection threshold
Topic:
LineSensor
Topic for publishing line position relative to the sensor**
**For further information regarding functionality of the sensors and actuators and topics for controlling or reading them, refer to the advanced manual configuration (Advanced Users).
37
HOW TO FLASH
In this section a way to flash the program binaries into the Puzzle-Bot along with the configuration files will be presented.
WINDOWS
1. Attach the microUSB cable to the Puzzle-Bot Control Module. Note the image is just
for explanation purposes, detachment of the Puzzle-Bot Control module from the robot is not necessary.
FIGURE 38 PUZZLE BOT CONTROL UNIT WITH MICRO USB
2. Make sure in the Bottom PCB that the Power Selector Switch is in the USB Position, and the Main Switch is turned ON.
FIGURE 39 PUZZLE-BOT BOTTOM PCB
3. Connect the USB to any free USB port in the computer
38
4. Decompress the Firmware files “FirmwareBin-1.x.x.zip” into a folder.
FIGURE 40 DECOMPRESS FIRMWARE FILE
5. Open the folder and select the corresponding operating system.
FIGURE 41 OPERATING SYSTEM SELECTION
6. Run FirmwareFlash.bat to flash the firmware to the esp32, the following screen should appear. Once finished press any key to exit.
FIGURE 42 UPLOADING FIRMWARE, FLASHING SCREENS (START AND FINISH)
7. Run DataFlash.bat to flash the data files to the esp32, the following screen should appear. Once finished press any key to exit.
FIGURE 43 UPLOADING DATA FILES TO MICROCONTROLLER
8. After finishing uploading the firmware and the data files the LCD display should start displaying information as seen in Figure 44.
39
FIGURE 44 INFORMATION BEING DISPLAYED BY THE LCD DISPLAY, AFTER FLASHING
9. PuzzeBot is ready to be used. Refer to the previous section on how to get started with the Puzzle-Bot. Please note that the configuration parameter file (YAML) inside the microcontroller still need to be configured, for using it with the Brushless or Brushed DC motor Version please refer to the section Configuration File (YAML file).
40
MATLAB ROBOTIC USER INTERFACE
One of the main features of the Puzzle-Bot is the capability of controlling it remotely using MATLAB. Manchester Robotics ltd. provide for this a MATLAB Robotic User Interface (MRUI) that includes the necessary libraries for simulating the Puzzle-Bot in its basic configuration and with the included sensors and actuators such as sonar, reflectance sensors and servo motors. At the same time, it provides the user the ability to connect and seamlessly test their own programs directly with the Puzzle-Bot.
FIGURE 45 MATLAB ROBOTIC USER INTERFACE (MRUI)
MATLAB Robotic User Interface by Manchester Robotics ltd. can be used in a multiple variety of ways depending on the user needs. For basic usage, two main ways (Stand Alone MRUI and Arduino style MRUI) of using the MATLAB Robotic User Interface will be shown in the subsequent sections.
WIFI COMMUNICATION
In this section, some basic information and set up when working with the real robot is described.
• The MRUI communication with the real robot is based on UDP WiFi protocol.
• The user might experience some communication lag because of WiFi network overload.
• Make sure that no other software interferes with the network (browser, etc.)
• Close the webpage of the robot (don’t use them in parallel).
• Try keeping a Line of sight between the robot and the computer (preferable).
• When implementing real time controllers, keep in mind, that the latency between MATLAB
and the microcontroller is around 20 ms depending on the computer performance.
41
STAND ALONE STYLE (SA-MRUI)
This is the most basic configuration available, in this mode the user uses the libraries available in MATLAB created by Manchester Robotics ltd. to connect to the real robot or the simulated robot and send/receive different signals from the real/simulated actuators or sensors. The user has the complete flexibility offered by MATLAB to set up its own variables, control loop timing and control strategy. The diagram shown in Figure 46 depicts the Stand-Alone Style of programming for a simple control loop. Some Examples on how to code in this mode will be shown in the subsequent sections.
FIGURE 46 STAND ALONE STYLE FOR A SIMPE CONTROL LOOP, A)PUZZLE-BOT, B)SIMULATED ROBOT
BASIC WORKFLOW OF THE STAND-ALONE PROGRAMMING STYLE
As stated before, in the stand-alone style of programming the MRUI, the user gets the flexibility of MATLAB programming by using the libraries provided by Manchester Robotics ltd. One of the most common ways of doing this is by following a simple control algorithm workflow as the one shown in the following figure.
FIGURE 47 BASIC WORKFLOW OF THE SA-MRUI METHOD
42
INITIALISATION
• Program Initialisation- In this section the user initializes the program by clearing all the
variables, make sure MATLAB is properly Set Up, and the path to the libraries is properly
defined.
• Initialise and connect the robot- This section can be further divided into two subsections
for real and simulated robots.
o Real Robot- Connect to the real robot using the libraries to set the IP address of the
robot and the name of the robot to be connected.
o Simulated Robot- In this part a simulated robot is created via a JSON file that
contains all the characteristics of the robot sensors and actuators as well as the variable definitions for each one of them to send or receive information. Further information on JSON files for robot designing in the subsequent sections. Manchester Robotics ltd. provides some pre-defined JSON files for the Puzzle-Bot System that contains the Motors, Encoders, servo motor and exteroceptive sensors such as Reflectance sensors and sonar.
• Initialise the World- In this section the user defines the world (2D-two dimensional world) where the robot is presented. This world can contain different obstacles defined by the user and it can be used when simulating LIDAR’s, Sonars and Line following sensors. The World, as the robot simulation is presented, in a JSON file that contains all the characteristics of the world such as coordinate system, obstacles, colour of obstacles etc. Further information about the World JSON files will be available in the subsequent sections. Manchester Robotics ltd. provides the users with some pre-defined Worlds, empty worlds for basic simulations and worlds with obstacles and lines for line following tasks.
• Global Variables Declaration- In this section the user can define and initialise the variables to be used in the code. Manchester Robotics ltd. will present some examples in the subsequent sections.
CONTROL LOOP
*Note that for the Purpose of a basic explanation a control loop is defined, the user can change this loop or redefine the programming method of the robot.
• Program Finished- In this section the user can establish any constrain for the control loop to finish. Some basic constrains can be time based or sensor based, etc.
• Receive Data from Sensors- In this section the user can get the data from the different sensors used in the robot such as encoders, sonar, reflectance etc. The variables where this information is stored depends on the JSON file for a particular simulated robot. The variables used for the real robot are given in the next section. Manchester Robotics ltd provides some examples on how to access these variables in the next sections. Note for simplicity the name of the variables in the JSON file (default) and the variables for robot communication are the same.
• Control Action- In this section the user can program the control action using the information received by the sensors in the previous point.
• Send Data to Actuators- As with the sensors, in this section the user is able to send the control action to the actuators using some pre-defined variables; for the simulation these variables are defined in the JSON files, and for the real robot these variables will be
43
provided in the following section. Note for simplicity the name of the variables in the JSON
file and the variable s for robot communication are the same.
• Save Data/ Plot- In this section the user is able to save the data for future use or plot the
data in real time (keep in mind that plotting can take some time when dealing with real
time control control).
• Plot Data-In this section the user can plot data if desired for visualisation.
• End Program- In this section the program ends.
44
GETTING STARTED STAND ALONE STYLE (SA-MRUI)
As stated before, this style of controlling the robot is based on the libraries provided by Manchester Robotics ltd. To start controlling the robot in this way the following steps must be followed.
SETTING UP THE MATLAB CONTROL ENVIRONMENT
1. Unzip the MATLAB Robotic User Interface (mobile-robot-matlab-ui.rar)
FIGURE 48 UNZIP THE MATLAB ROBOTICS USER INTERFACE
2. The MRUI folder contains different files as shown in Figure 49, each file will be explained in the subsequent sections.
FIGURE 49 MRUI FOLDER FILES
3. Open MATLAB and change the current folder address tab in MATLAB to the path where the MRUI folder is located; you can verify this since the folders inside MRUI appear in the current folder tab.
FIGURE 50 MATLAB SETUP:SETTING PATH
45
4. Create a New Script from the Home Tab>New Script as shown in the following figure.
FIGURE 51 MATLAB NEW SCRIPT
5. Now the user can start using the libraries provided by Manchester Robotics ltd. to control the real/simulated robot. More information about these libraries as well as some examples can be found in the subsequent sections.
6. Once the Program is done, it can be run by going into the Editor Tab>Run
FIGURE 52 RUNNING THE PROGRAM
46
EXAMPLES STAND-ALONE STYLE (SA-MRUI)
The following examples are for the Stand-Alone style, this require the Real robot to receive PWM signals to the motor as seen in Configuration File (YAML file) section when defining the Main Parameters of the Robot>Robot>Control Input>3 (for PWM control input).
The following examples follow the basic workflow shown in Figure 47.
EXAMPLE STAND-ALONE PWM
This example simulates a robot (can be connected to the real robot), into a basic world and sends some PWM signals to the motors, saves the data and plots the speeds of the wheels given by the encoders.
• This example Simulates a robot (robot_0002 can be found in the folder hardware_definitions>robot_0002) comprised of a differential drive robot (DDR)with two motors with encoders in each motor and a Sonar attached to a Servo motor.
• Detailed comments are provided in the example file. In order to use the real robot uncomment the line and set the robot IP as follows R1.connect(‘ROBOT IP’).
• The simulated world used for this test is the world_0002 consisting in world with basic figures (world_examples>world_0002.json).
• Send the PWM signals [-1, 1] as defined in General Specs, directly to the Robot Motors.
• Using the PWM signals the robot is updated via R1.update() and now the user can access
the sensor information using the appropriate topic.
• Save the data provided by the encoders in each motor and when the simulation finishes,
plots the results.
• To run the following example, follow step 5 and 6 in Setting Up The MATLAB Control
Environment.
clc, clear all
restoredefaultpath
addpath(genpath(pwd))
% Create Robot
R1 = RobotClass(‘json_fname’, ‘robot_0002.json’);
% Uncomment below for using the real robot (it’s simulation otherwise) % R1.connect(‘192.168.1.1’);
% Create World
W = WorldClass(‘fname’, ‘world_0002.json’);
% Total duration and sampling time parameters
TotalTime = 1;
t_sampling = 0.02;
t_start = tic;
t_loop = tic;
% Wheel control pwm signals [-1,1]
uR = 1;
uL = 0.5;
wR_all = [0];
wL_all = [0];
while toc(t_start)
% Update robot in this order: actuators, pose (in simulation), sensors
if toc(t_start)>0.0 actuator_signals = {‘right motor’, else
actuator_signals = {‘right motor’, end
sensor_readings = R1.update(dt, W,
% Update encoder velocity readings
uR, ‘left motor’, uL};
0, ‘left motor’, 0};
‘kinematics’, ‘voltage_pwm’, actuator_signals{:});
wR = sensor_readings(‘right encoder’); wL = sensor_readings(‘left encoder’);
% Save data for ploting
wR_all = [wR_all wR];
wL_all = [wL_all wL];
end
pause(0.001)
end
% plot saved velocities for right and left wheels
plot(wR_all);
hold on
plot(wL_all);
FIGURE 53 OUTPUT OF THE STAND-ALONE PWM EXAMPLE
48
EXAMPLE STAND-ALONE CONTROL
This example simulates a robot (can be connected to the real robot), into a basic world. A PID controller is then used to provide the PWM signals to the motors in order to achieve the set points, saves the data coming from encoders and plots the speeds of the wheels. In this example a PID controller library provided by Manchester Robotics ltd. is used, the user can access this library in core>utils>MotorControl.m.
clc, clear all
restoredefaultpath
addpath(genpath(pwd))
% Create Robot
R1 = RobotClass(‘json_fname’, ‘robot_0002.json’);
% Uncomment below for using the real robot (it’s simulation otherwise) % R1.connect(‘192.168.1.1’);
% Create World
W = WorldClass(‘fname’, ‘world_0002.json’);
% Total duration and sampling time parameters
TotalTime = 2;
t_sampling = 0.02;
t_start = tic;
t_loop = tic;
% Initialise motor angular velocity controllers
control_right = MotorControl(); control_left = MotorControl();
% Controller setpoints for right and left wheel
wR_set = 7;
wL_set = 6;
wR = 0; wL = 0;
wR_all = [0];
wL_all = [0];
while toc(t_start)
t_loop = tic;
49
wR = sensor_readings(‘right encoder’); wL = sensor_readings(‘left encoder’);
% Save data for ploting
wR_all = [wR_all wR];
wL_all = [wL_all wL];
end
pause(0.001)
end
% Plot wheel angular velocities
plot(wR_all);
hold on;
plot(wL_all);
FIGURE 54 OUTPUT FROM STAND-ALONE CONTROL EXAMPLE
50
EXAMPLE STAND-ALONE SONAR
This example simulates a robot (can be connected to the real robot), into a world with a wall in the shape of a circle as shown in Figure 55. A cascade control strategy is used keep the robot at a desired distance from the obstacle. In this example the outer loop is in shcarge with keeping the constant distance to the obstacle and provides the set-points to the inner loop. The inner loop then runs a PID controller that provides the PWM signals to the motors. The program plots the position of the robot iteratively to simulate the movement of the robot.
clc, clear all, close all
restoredefaultpath
addpath(genpath(pwd))
% Create Robot (robot with reflectance,sonar and servo motor)
R1 = RobotClass(‘json_fname’, ‘puzzle_bot_0002.json’);
% Uncomment below for using the real robot (it’s simulation otherwise) % R1.connect(‘192.168.1.1’);
% Create World
W = WorldClass(‘fname’, ‘world_wall.json’);
% Plot world and robot
figure(1)
h_w = W.plot();
% Total duration and sampling time parameters
TotalTime = 10;
sampling_inner = 0.02;
sampling_outer = 0.1;
t_start = tic;
t_outer_loop = tic;
t_inner_loop = tic;
% Initialise motor angular velocity controllers
control_right = MotorControl(); control_left = MotorControl();
% Desired wheel velocities
wR_set = 0;
wL_set = 0;
wR = 0; wL = 0;
% desired wheel velocity
w_desired = 5;
% Proportional gain for following the wall
K = 5;
while toc(t_start)
sonar_dist = sensor_readings(‘sonar’);
% If a wall is found less than 1m away from the robot then follow it
if sonar_dist < 1
err_dist = 0.5 - sonar_dist; % hold a constant distance of 0.5m to the wall wR_set = w_desired - K*err_dist;
51
wL_set = w_desired + K*err_dist;
else
wR_set = 0;
wL_set = 0;
end
% Plot all
try
catch
end
h_r = R1.plot('simple');
h_s = R1.plot_measurements('sonar');
end
%% Inner loop
dt = toc(t_inner_loop);
if(dt>=sampling_inner) % execute code when desired inner loop sampling time is reached
t_inner_loop = tic;
uR = control_right.Control(wR_set-wR,dt); uL = control_left.Control(wL_set-wL,dt);
% Update robot in this order: actuators, pose (in simulation), sensors
% Set the servo angle to 60 degrees to the left, 1 radian (where the wall should be) actuator_signals = {‘right motor’, uR, ‘left motor’, uL,’servo motor’,1}; sensor_readings = R1.update(dt, W, ‘kinematics’, ‘voltage_pwm’, actuator_signals{:});
% Update encoder velocity readings
wR = sensor_readings(‘right encoder’); wL = sensor_readings(‘left encoder’);
end
pause(0.001)
end
actuator_signals = {‘right motor’, 0, ‘left motor’, 0,’servo motor’,0}; R1.update(dt, W, ‘kinematics’, ‘voltage_pwm’, actuator_signals{:});
FIGURE 55 OUTPUT OF THE STAND-ALONE SONAR EXAMPLE
delete([h_r, h_s])
52
ARDUINO STYLE (A-MRUI)
This is another style of programming the MATLAB Robotic User Interface, different from the Stand- Alone Version, where the user had to develop from scratch the control loop, select when to update the simulated robot states and develop its own GUI, using the libraries provided by Manchester Robotics ltd.
In this style of programming the MATLAB Robotic User Interface runs a predefined Continuous Loop, automatically updating the information from the robot sensors and actuators, the user control code, and the Graphical User Interface (GUI).
In other words, the main difference between this programming style and the one mentioned in the Stand Alone Style section, is that in this style the user does not have to worry about updating the robot, setting the control loop or implementing a graphic user interface, but only on the control algorithm for the robot.
As stated before, in this type of programming style, the user code runs repeatedly inside the loop as shown in the following figure.
FIGURE 56 ARDUINO STYLE PROGRAMMING
To make the programming of the Controller easy for the user, the MATLAB User Code section is subdivided into two sections based on the Arduino programming paradigm. The setup section and the loop section.
The setup section consists of a part of the program used for setting up the variables to be used by the program, this section runs only one time in the continuous loop.
The loop section is the section that run continuously with the loop. This section defined by the user will oversees the updating the signals to be sent or manage the ones received from to/from the actuators and/or sensors, as well as implementing the control algorithm defined by the user. The loop and setup section can be seen the following diagram.
53
FIGURE 57 SETUP AND LOOP SECTIONS IN THE MATLAB USER CODE
In the following sections some basic functionalities and examples on how to use the MATLAB Robotic User Interface with this programming style will be shown.
Note, the Continuous Loop (Big Loop) described in the figure by the blue arrow surrounding everything; can also be configured by the user for further reference go to the Advance user Manual.
54
STARTING THE MATLAB ROBOTIC USER INTERFACE (MRUI)
In this section a basic tutorial on how to set up the MATLAB Robotic User Interface by Manchester Robotics ltd. will be shown.
1. Unzip the MATLAB Robotic User Interface (mobile-robot-matlab-ui.rar)
FIGURE 58 UNZIP THE MATLAB ROBOTICS USER INTERFACE
2. The MRUI folder contains different files as shown in the following figure, each file will be explained in the subsequent sections.
FIGURE 59 MRUI FOLDER FILES
3. Open the MRUI by selecting the mobile_robot_platform.m file. Shown in Figure 59 in blue.
4. The following screen should appear
FIGURE 60 MATLAB MRUI
55
5. Make sure the current folder address tab in MATLAB has the folder address where the MRUI folder is located; by verifying the folders inside MRUI appear in the current folder tab. Note If you click the Run button, the directory tab changes automatically, but sometimes this might fail due to MATLAB.
FIGURE 61 FOLDERS IN MRUI
6. Run the program from the editor tab in MATLAB.
FIGURE 62 EDITOR TAB AND RUN BUTTON IN MATLAB
7. The following screen should appear. Note, since there is no control program at his time the Robot (represented by the red triangle will not move). Follow the steps in the next section to run an example program.
FIGURE 63 MOBILE ROBOTIC USER INTERFACE
56
RUNNING A PROGRAM IN THE MATLAB ROBOTIC USER INTERFACE
For this section the example program drive_straight located in mobile-robot-matlab- ui/my_examples will be used to show the user how to tun a program in the GUI.
1. Follow the steps in section Starting the MATLAB Robotic User Interface (MRUI).
2. Select the Robot to be used for this simulation. For this example, the robot described by the JSON file puzzle_bot_0002.json (default) will be used. This robot is comprised by a
Differential drive robot with reflectance, servo and a sonar attached to the servo.
FIGURE 64 SET UP THE ROBOT FOR SIMULATION
3. Set Up the Control File used for this simulation. For this case, the example file drive_straight will be used.
FIGURE 65 SET UP THE CONTROL FILE
57
4. For this case since it is a simulation the IP Address and the Communication status of the robot can be left ‘as is’.
FIGURE 66 IP ADDRESS AND COMMUNICATION STATUS TAB
5. The user can change the initial position of the robot by changing the values in the pose tab.
FIGURE 67 SET UP THE ROBOT POSITION
6. The World used for the simulation can be defined by clicking the World Button and selecting it from a JSON file. For this example, the default empty world will be used.
58
FIGURE 68 SET UP THE WORLD TO BE USED
7. Use the Run and Stop buttons to start and stop the simulation and the Pan and Zoom buttons to move inside the plot.
FIGURE 69 START AND STOP THE SIMULATION
8. The result should look like the following image. Note the rest of the GUI function will be described in the subsequent sections.
59
FIGURE 70 ROBOT AFTER SIMULATION
60
GUI DESCRIPTION
As stated in the previous sections, the GUI sets some basic variables used in the program, such as the type of robot, the world, the control file and the connection to the robot. At the same time it works as a user interface with the robot for the user. In this section rest of the functions from the GUI will be described.
TABLE 9 GUI DESCRIPTION TABLE
FIGURE 71 MATLAB ROBOTIC USER INTERFACE GUI
GUI
Description
Robot
Robot representation in the GUI.
Pan, Zoom
Pan and Zoom in the plot area.
World Selection
Select the JSON file containing the world. File selector window will pop-up.
World Editor
Edit the current World. See subsequent sections.
World Save
Save the edited world.
Add Robot
Add a new robot. For multiple robot simulation (Advanced users).
Run Session
Start simulation/ real robot.
Stop Session
Stop the session
File Name
Set the JSON file defining the robot to be used.
Control File
Set the control file to be used.
IP Address
IP address of the real robot.
2D Pose
Initial Pose of the robot.
Connection Status
Status Connection of the real robot.
Robot Visualisation
Visualisation of the Robot Used (defined by the JSON file in the File Used tab )
61
WORLD EDIT
One of the main characteristics of the GUI is the flexibility given to the user to edit the current world, generate its own world and save it for future use. In this section a basic world will be done as an example, using the empty (default world).
1. Initialise the MATLAB Robotic User Interface as done in the section: Starting the MATLAB Robotic User Interface (MRUI).
2. Click on the World Editor Button.
FIGURE 72 WORLD EDITOR BUTTON
3. The following World Editor Mode Screen will appear.
FIGURE 73 WORLD EDITOR MODE
4. Follow the instructions given in the top bar of the GUI. To Exit the Editor Mode press ESC on the keyboard.
62
FIGURE 74 INSTRUCTION FOR EDITING THE WORLD.
The user can define different objects in the map such as Polygons, Circles, Points and a Path (for line following). For each object follow the instructions at the top bar (Figure 74).
FIGURE 75 OBJECT SELECTOR.
5. For the Polygon shape use the mouse to move the Crosshair and define the points of the obstacle and the SPACE key (in the keyboard) to close the shape.
6. For the circle use the crosshair to define the centre and click again to define the radius.
7. For the point just select using the crosshair the position.
8. For the path use the crosshair to define the points of the path.
63
FIGURE 76 DIFFERENT FIGURES DRAWN USING THE WORLD EDITOR.
9. To delete a figure, select the Figure Delete button and use the crosshair to delete the selected figure.
10. Once you have finished editing the World, press ESC to go back to normal mode.
11. Save the World for future use by pressing the Button Save World. A pop-up window will
appear, name your world and then press Save.
FIGURE 77 SAVE WORLD
64
EXAMPLE OF A BASIC CONTROL ALGORITHM
In this section a basic control algorithm will be presented. This example can be found in my_examples>drive_straight.
Recall the way the MATLAB Robotic User Interface program works in the following diagram.
FIGURE 78 BASIC WORKFLOW OF THE MRUI FOR THE ARDUINO PROGRAMMING STYLE
As stated previously the controller part programming defined by the user is based on the Arduino style of programming. In which the user has a setup section and a loop section to run its code one time and multiple times, respectively.
FIGURE 79 CONTROL TEMPLATE COMPARISON WITH ARDUINO TEMPLATE
65
As seen in the previous figure, the control function template contains two pre-defined structures my_alg and robot.
The robot container structure handles all the internal variables of the robot for the proper function of the MATLAB Robotics User Interface. Modifying this structure is not recommended for basic users.
The my_alg is a container (hash table of the class container.map) dedicated for the user to define and add its own variables or problem-specific parameters as elements to the my_alg structure that will persist throughout the session. At the same time this container has some global elements to be understood by the MATLAB Robotics User Interface that contain information regarding simulation variables to be managed by the user. The following table shows the global elementes pre-defined in my_alg.
TABLE 10 MY_ALG STRUCTURE
MyAlg Structure
Description
my_alg(‘tic’)
Returns an identifier to the start time of session. To compute the current time use toc(my_alg(‘tic’))
my_alg(‘is_first_time’)
Returns a boolean to indicate whether the iteration is the first one. This element can be used to initialize parameters needed for the algorithm.
my_alg(‘is_done’)
Set a boolean to terminate the session programmatically.
my_alg(‘dc_motor_signal_mode’)
Returns a string defining the signal mode. Options are {‘omega_setpoint’, ‘voltage_pwm’}
my_alg(…)
Returns the value of the actuator or sensor labelled … in robot JSON-file as follows.
• my_alg(‘right encoder’)
Right encoder velocity
• my_alg(‘left encoder’)
Left encoder velocity
• my_alg(‘reflectance’)
Reflectance sensor output value
• my_alg(‘sonar’)
Sonar measured distance (m)
• my_alg(‘right motor’)
Sets the right motor input signal (pwm or angular velocity)
• my_alg(‘left motor’)
Sets the left motor input signal (pwm or angular velocity)
• my_alg(‘servo motor’)
Sets the servomotor angle (radians)
my_alg(‘Name’)
Definition of a variable to be added to my_alg by the user. The ’Name’ can be replaced by any name defined by the user.
66
EXAMPLE BASIC
function my_alg = drive_straight(my_alg, robot)
% This function drives the robot in a straight line for 10 seconds.
% Then, it stops.
%
% Mohamed Mustafa, August 2020
% ————————————————————————-
if my_alg(‘is_first_time’)
my_alg(‘dc_motor_signal_mode’) = ‘omega_setpoint’; % change if necessary to ‘voltage_pwm’
end
time = toc(my_alg(‘tic’));
if time < 10
% Drive
my_alg('right motor') = 5;
my_alg('left motor') = 5;
else
% Stop motors
my_alg('right motor') = 0;
my_alg('left motor') = 0;
% Stop session
my_alg('is_done') = true;
end
% display encoder readings
% Get time since start of session
left_encoder_omega = my_alg('left encoder');
right_encoder_omega = my_alg('right encoder');
%['Encoders (left, right): (' num2str(left_encoder_omega) ', ' num2str(right_encoder_omega) ') rad/sec.']
return
To run this example, follow the steps defined in section: Running a Program in the MATLAB Robotic User Interface.
67
OTHER CONTROL ALGORITHM EXAMPLES
function my_alg = example_control(my_alg, robot)
% This function implements velocity controllers for both wheels
% and applies the desired setpoints for a specified amount of time. %
% Mohamed Mustafa, August 2020
%
%
%
%
%
%
%
%
%
%
%
%
%
------------------------------------------------------------------------- Reading data from sensors (if present on the robot)
my_alg('right encoder')
my_alg('left encoder')
my_alg('reflectance')
my_alg('sonar')
- right encoder velocity
- left encoder velocity
- reflectance sensor output value
- sonar measured distance (m)
Sending controls to actuators (if present on the robot)
my_alg('right motor')
my_alg('left motor')
my_alg('servo motor')
- sets the right motor input signal (pwm or angular velocity) - sets the left motor input signal (pwm or angular velocity) - sets the servomotor angle (radians)
-------------------------------------------------------------------------
if my_alg('is_first_time')
%% Setup initial parameters here
my_alg('dc_motor_signal_mode') = 'voltage_pwm';
% Initialise wheel angular velocity contollers
my_alg('wR_set') = 7;
my_alg('wL_set') = 6;
my_alg('control_right') = MotorControl(); my_alg('control_left') = MotorControl();
% Initialise vectors for saving velocity data
% change if necessary to 'omega_setpoint'
my_alg('wR_all') = [];
my_alg('wL_all') = [];
% Initialise time parameters
my_alg('t_sampling') = 0.02;
my_alg('t_loop') = tic;
my_alg('t_finish') = 2;
end
%% Loop code runs here
time = toc(my_alg('tic'));
if time < my_alg('t_finish')
% Get time since start of session
% Check for algorithm finish time
dt = toc(my_alg('t_loop'));
if dt>my_alg(‘t_sampling’) %
my_alg(‘t_loop’) = tic;
% Right wheel controller %%%%%%%%%%%%%%%%%%%%
errR = my_alg(‘wR_set’) – my_alg(‘right encoder’); uR = my_alg(‘control_right’).Control(errR,dt);
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Left wheel controller %%%%%%%%%%%%%%%%%%%%%
errL = my_alg(‘wL_set’) – my_alg(‘left encoder’); uL = my_alg(‘control_left’).Control(errL,dt);
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Apply pwm signal
my_alg(‘right motor’) = uR;
my_alg(‘left motor’) = uL;
68
my_alg(‘wR_all’) = [my_alg(‘wR_all’) my_alg(‘right encoder’)]; my_alg(‘wL_all’) = [my_alg(‘wL_all’) my_alg(‘left encoder’)];
end else
%% Finish algorithm and plot results
% Stop motors
my_alg(‘right motor’) = 0;
my_alg(‘left motor’) = 0;
% Stop session
my_alg(‘is_done’) = true;
% Plot saved velocities for right and left wheel
figure(2);
plot(my_alg(‘wR_all’));
hold on
plot(my_alg(‘wL_all’));
end
return
Note Further examples and instructions on how to use them, can be found in my_examples.
69
PINOUT DIAGRAMS
FIGURE 80 PUZZLE-BOT CONTROL MODULE (BOTTOM PCB)
70
FIGURE 81 PUZZLE-BOT CONTROL MODULE EXTENSION (TOP PCB)
71
FIGURE 82 SONAR PLACEMENT DIAGRAM
72
FIGURE 83 SONAR AND SERVO CONNECTION
73
ASSEMBLY MANUAL BRUSHLESS VERSION
74
75
76
77
78
*Drawings are no to scale
79
ASSEMBLY MANUAL BRUSHED DC MOTOR VERSION
80
81
82
83
*To connect the motors to the PCB, check section Pinout Diagrams
84
*Drawings are no to scale
85
SONAR ATTACHMENT
*For cables connection of the sonar and servo motor, check section Pinout Diagrams.
86
REFLECTANCE SENSOR ATTACHMENT
87
APPENDIX
SENSOR AND ACTUATOR DATASHEETS
Datasheets for the sensors and actuators can be found in the following webpages.
Motor DC Brushed and encoder:
https://www.pololu.com/product/4824
Motor Brushless and encoder:
https://wiki.dfrobot.com/FIT0441_Brushless_DC_Motor_with_Encoder_12V_159RPM
Servo Motor: https://www.pololu.com/product/2818
Sonar Sensor:
https://www.parallax.com/sites/default/files/downloads/28015-PING-Sensor-Product-Guide- v2.0.pdf
Reflectance Sensor: https://www.pololu.com/product/4153
88
PUZZLE-BOT PARAMETER FILE
TABLE 11 PUZZLE-BOT PARAMETER FILE
Parameter Description
PidDt: Pid controller loop sampling time
Main parameters for the robot
Robot:
Type: 1-differential drive robot; 2-holonomic robot
ControlInput: 1-robot linear and angular velocities; 2-wheel angular velocities setpoints; 3-
wheel pwm voltage signals WheelBase: Half of the robot width
WheelRadius: Wheel radius
TopicVx: Topic for receiving linear velocity of the robot
TopicVy: Topic for receiving linear velocity of the robot on Y(for holonomic robot)
TopicW: Topic for receiving angular velocity of the robot
Parameters for the right wheel
RightWheel:
Motor: Right motor parameters
Pins: Motor driver pins
Sign: Motor direction setting (-1/1) Type: Motor type. 1-brushless; 2-brushed Topic: Topic for receiving control pwm
Encoder: Right encoder parameters Pins: Encoder pins
Sign: Encoder direction setting (-1/1)
Ticks: Encoder number of ticks for one rotation
Gear: Gear ratio
Type: 2 Encoder type. 1-single pulse(no direction); 2-double pulse(with
direction)
MeasureType: Encoder velocity measurement type.
1-count pulses; 2-measure pulse
duration
Topic: Encoder velocity publish topic
Pid: Right Pid controller parameters Kp: Proportional gain
Ti: Integration time
Td: Derivation time
Default Value
0.01
1
3
0.083
0.0505
VelocityLinearX
VelocityLinearY
VelocityAngular
[4, 15, 18]
1
2
ControlR
[36, 34]
-1
48
34
2
1
VelocityEncR
0.1
0.05
0
89
0.1
VelocitySetR
DeadZone: Motor control dead zone
Topic: Topic for receiving velocity setpoint
Parameters for the left wheel
LeftWheel:
Motor: Left motor parameters
Pins: Motor driver pins
Sign: Motor direction setting (-1/1) Type: Motor type. 1-brushless; 2-brushed Topic: Topic for receiving control pwm
Encoder: Left encoder parameters
Pins: Encoder pins
Sign: Encoder direction setting (-1/1)
Ticks: Encoder number of ticks for one rotation
Gear: Gear ratio
Type: Encoder type. 1-single pulse(no direction); 2-double pulse(with
direction)
MeasureType: Encoder velocity measurement type.
1-count pulses; 2-measure pulse
duration
Topic: Encoder velocity publish topic
Pid: Left Pid controller parameters Kp: Proportional gain
Ti: Integration time
Td: Derivation time
DeadZone: Motor control dead zone
Topic: Topic for receiving velocity setpoint
Parameters for sonar
Sonar:
Pins: Sonar pins
Topic: Topic for publishing sonar measured distance
Parameters for servo motor
Servo:
Pins: Servo motor pins
Offset: Servo motor center offset
Topic: Topic for receiving servo motor angle
(degrees)
[2, 12, 0]
-1
2
ControlL
[39, 35]
1
48
34
2
1
VelocityEncL
0.1
0.05
0
0.1
VelocitySetL
14
SonarDistance
5
0
ServoAngle
Parameters for reflectance sensor
Reflectance:
90
NPins:
6
Pins:
[32, 25, 27, 19, 23, 22]
EmitterPins:
[13, 12]
EmitterSelect:
2
MinValues:
[600, 600, 600, 600, 600, 600]
MinAvg:
2000
Threshold:
1.1
Topic:
LineSensor
Network parameters
Number of pins (number of light sensors used)
Reflectance pins
Emitter pins (for selecting even/odd lights on/off)
Emitter selector. 1-even; 2-odd; 3-all
Minimal reflectance values measured during calibration (use webpage)
Minimal reflectance average value measured during calibration
Line detection treshold
Topic for publishing line position relative to the sensor
Access point ssid Access point password Access point IP
Ros master IP (when ros connection is active)
Port for the web server
Port for data communication server (tcp/udp)
Wifi transmitter power (78 is maximum) Domain name for the webpage
Servo motor on/off (1/0)
Sonar on/off (1/0)
Reflectance sensorr on/off (1/0) Screen on/off (1/0)
Ros communication on/off (1/0)
Network:
SSID:
Puzzlebot1
Password:
Puzzlebot72
IP:
[192, 168, 1, 1]
RosIP:
[192, 168, 1, 2]
PortWeb:
80
PortData:
3141
WiFiPower:
78
WebPage:
puzzlebot
Active modules settings
ActiveModules:
Servo:
1
Sonar:
1
Reflect:
1
Screen:
1
Ros:
0
91
NOTES
92