├── .gitignore ├── .gitmodules ├── LICENSE ├── README.md ├── _config.yml └── arduino-board ├── Makefile ├── order.h ├── parameters.h ├── slave.cpp ├── slave.h └── slave ├── order.h ├── parameters.h ├── slave.h └── slave.ino /.gitignore: -------------------------------------------------------------------------------- 1 | bin/ 2 | *.log 3 | .vscode/ -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "rust-arduino-serial"] 2 | path = rust-arduino-serial 3 | url = https://github.com/araffin/rust-arduino-serial 4 | [submodule "cpp-arduino-serial"] 5 | path = cpp-arduino-serial 6 | url = https://github.com/araffin/cpp-arduino-serial.git 7 | [submodule "python-arduino-serial"] 8 | path = python-arduino-serial 9 | url = https://github.com/araffin/python-arduino-serial.git 10 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2018 Antonin RAFFIN 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Robust Arduino Serial Protocol 2 | 3 | **Robust Arduino Serial** is a simple and robust serial communication protocol. It was designed to make two Arduinos communicate, but can also be useful when you want a computer (e.g. a Raspberry Pi) to communicate with an Arduino. 4 | 5 | **Please read the [Medium Article](https://medium.com/@araffin/simple-and-robust-computer-arduino-serial-communication-f91b95596788) to have an overview of this protocol.** 6 | 7 | Implementations are available in various programming languages: 8 | 9 | - Arduino (`arduino-serial/` folder) 10 | - [Python](https://github.com/araffin/python-arduino-serial) 11 | - [C++](https://github.com/araffin/cpp-arduino-serial) 12 | - [Rust](https://github.com/araffin/rust-arduino-serial) 13 | 14 | 15 | **Examples** are provided in each repository. 16 | 17 | To clone all the repositories at once, tou need to use the `--recursive` command: 18 | ``` 19 | git clone https://github.com/araffin/arduino-robust-serial.git --recursive 20 | ``` 21 | 22 | Table of Contents 23 | ================= 24 | 25 | * [Provided Functions](#provided-functions) 26 | * [Arduino Implementation](#arduino-implementation) 27 | * [1. Using Arduino IDE](#1-using-arduino-ide) 28 | * [2. Using Arduino Makefile (Recommended)](#2-using-arduino-makefile-recommended) 29 | * [Python Implementation](#python-implementation) 30 | * [C Implementation](#c-implementation) 31 | * [Rust Implementation](#rust-implementation) 32 | * [Real Life Example](#real-life-example) 33 | * [Acknowledgments](#acknowledgments) 34 | 35 | 36 | ### Provided Functions 37 | 38 | Please check examples in the different repos to have the parameters details for each programming language. 39 | 40 | - `read_order()`: Read one byte from a file/serial port and convert it to an order (equivalent to read_i8) 41 | - `read_i8()`: Read one byte from a file/serial port and convert it to a 8 bits int 42 | - `read_i16()`: Read one byte from a file/serial port and convert it to a 16 bits int 43 | - `read_i32()`: Read one byte from a file/serial port and convert it to a 32 bits int 44 | - `write_order()`: Write an order to a file/serial port. (equivalent to write_i8) 45 | - `write_i8()`: Write one byte int to a file/serial port. 46 | - `write_i16()`: Write two bytes (16-bits) int to a file/serial port. 47 | - `write_i32()`: Write four bytes (32-bits) int to a file/serial port. 48 | 49 | 50 | ### Arduino Implementation 51 | 52 | #### 1. Using Arduino IDE 53 | 54 | Open `arduino-board/slave/slave.ino` in your Arduino IDE. 55 | 56 | #### 2. Using Arduino Makefile (Recommended) 57 | 58 | This method only works with Linux/Mac Os systems: [https://github.com/sudar/Arduino-Makefile](https://github.com/sudar/Arduino-Makefile) 59 | 60 | Install Arduino Makefile. 61 | ``` 62 | sudo apt-get install arduino-mk 63 | ``` 64 | 65 | Compile and upload the code to the Arduino (please check the board name in the Makefile): 66 | ``` 67 | cd arduino-board/ 68 | make 69 | make upload 70 | ``` 71 | 72 | ### Python Implementation 73 | 74 | [![Build Status](https://travis-ci.org/araffin/python-arduino-serial.svg?branch=master)](https://travis-ci.org/araffin/python-arduino-serial) 75 | 76 | Python repository: [https://github.com/araffin/python-arduino-serial](https://github.com/araffin/python-arduino-serial) 77 | 78 | ### C++ Implementation 79 | 80 | [![Build Status](https://travis-ci.org/araffin/cpp-arduino-serial.svg?branch=master)](https://travis-ci.org/araffin/cpp-arduino-serial) 81 | 82 | 83 | C++ repository: [https://github.com/araffin/cpp-arduino-serial](https://github.com/araffin/cpp-arduino-serial) 84 | 85 | 86 | ### Rust Implementation 87 | 88 | [![Build Status](https://travis-ci.org/araffin/rust-arduino-serial.svg?branch=master)](https://travis-ci.org/araffin/rust-arduino-serial) [![Build status](https://ci.appveyor.com/api/projects/status/h0ejgesat0nnpahc/branch/master?svg=true)](https://ci.appveyor.com/project/araffin/rust-arduino-serial/branch/master) 89 | 90 | Rust repository: [https://github.com/araffin/rust-arduino-serial](https://github.com/araffin/rust-arduino-serial) 91 | 92 | ### Real Life Example 93 | 94 | This protocol was used on the Racing Robot: [https://github.com/sergionr2/RacingRobot](https://github.com/sergionr2/RacingRobot) 95 | 96 | [![The racing robot](https://cdn-images-1.medium.com/max/2000/1*UsmiJ4IzXi6U9svKjB22zw.jpeg)](https://www.youtube.com/watch?v=xhI71ZdSh6k) 97 | 98 | ### Acknowledgments 99 | 100 | I would like to thanks Dara Ly for the original idea of communicating with the Arduino via a command parser, and Xuan Zhang for fixing Arduino limited buffer issue. 101 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | theme: jekyll-theme-architect -------------------------------------------------------------------------------- /arduino-board/Makefile: -------------------------------------------------------------------------------- 1 | ### DISCLAIMER 2 | ### This is an example Makefile and it MUST be configured to suit your needs. 3 | ### For detailled explanations about all the avalaible options, 4 | ### please refer to https://github.com/sudar/Arduino-Makefile/blob/master/arduino-mk-vars.md 5 | ### Original project where this Makefile comes from: https://github.com/WeAreLeka/Bare-Arduino-Project 6 | 7 | ### PROJECT_DIR 8 | ### This is the path to where you have created/cloned your project 9 | PROJECT_DIR = $(shell pwd) 10 | 11 | ### ARDMK_DIR 12 | ### Path to the Arduino-Makefile directory. 13 | ARDMK_DIR = /usr/share/arduino 14 | 15 | ### ARDUINO_DIR 16 | ### Path to the Arduino application and ressources directory. 17 | 18 | ### or on Linux: (remove the one you don't want) 19 | ARDUINO_DIR = /usr/share/arduino 20 | 21 | ### USER_LIB_PATH 22 | ### Path to where the your project's libraries are stored. 23 | USER_LIB_PATH := $(PROJECT_DIR)/lib 24 | 25 | ### BOARD_TAG 26 | ### It must be set to the board you are currently using. (i.e uno, mega2560, etc.) 27 | BOARD_TAG = uno 28 | 29 | ### MONITOR_BAUDRATE 30 | ### It must be set to Serial baudrate value you are using. 31 | MONITOR_BAUDRATE = 115200 32 | 33 | ### AVR_TOOLS_DIR 34 | ### Path to the AVR tools directory such as avr-gcc, avr-g++, etc. 35 | ### On OS X with `homebrew`: 36 | AVR_TOOLS_DIR = /usr/local 37 | ### or on Linux: (remove the one you don't want) 38 | AVR_TOOLS_DIR = /usr 39 | 40 | ### AVRDUDE 41 | ### Path to avrdude directory. 42 | ### On OS X with `homebrew`: 43 | AVRDUDE = /usr/local/bin/avrdude 44 | ### or on Linux: (remove the one you don't want) 45 | AVRDUDE = /usr/bin/avrdude 46 | 47 | ### AVRDUDE_CONF 48 | ### Path to avrdude config file. 49 | #AVRDUDE_CONF = /etc/avrdude.conf 50 | 51 | ### CFLAGS_STD 52 | ### Set the C standard to be used during compilation. Documentation (https://github.com/WeAreLeka/Arduino-Makefile/blob/std-flags/arduino-mk-vars.md#cflags_std) 53 | CFLAGS_STD = -std=gnu11 54 | 55 | ### CXXFLAGS_STD 56 | ### Set the C++ standard to be used during compilation. Documentation (https://github.com/WeAreLeka/Arduino-Makefile/blob/std-flags/arduino-mk-vars.md#cxxflags_std) 57 | CXXFLAGS_STD = -std=gnu++11 58 | 59 | ### CXXFLAGS 60 | ### Flags you might want to set for debugging purpose. Comment to stop. 61 | CXXFLAGS += -pedantic -Wall -Wextra 62 | 63 | ### MONITOR_PORT 64 | ### The port your board is connected to. Using an '*' tries all the ports and finds the right one. 65 | MONITOR_PORT = /dev/ttyACM* 66 | 67 | ### CURRENT_DIR 68 | ### Do not touch - used for binaries path 69 | CURRENT_DIR = $(shell basename $(CURDIR)) 70 | 71 | ### OBJDIR 72 | ### This is were you put the binaries you just compile using 'make' 73 | OBJDIR = $(PROJECT_DIR)/bin/$(BOARD_TAG)/$(CURRENT_DIR) 74 | 75 | ### path to Arduino.mk, inside the ARDMK_DIR, don't touch. 76 | include $(ARDMK_DIR)/Arduino.mk 77 | -------------------------------------------------------------------------------- /arduino-board/order.h: -------------------------------------------------------------------------------- 1 | #ifndef ORDER_H 2 | #define ORDER_H 3 | 4 | // Define the orders that can be sent and received 5 | enum Order { 6 | HELLO = 0, 7 | SERVO = 1, 8 | MOTOR = 2, 9 | ALREADY_CONNECTED = 3, 10 | ERROR = 4, 11 | RECEIVED = 5, 12 | STOP = 6, 13 | }; 14 | 15 | typedef enum Order Order; 16 | 17 | #endif 18 | -------------------------------------------------------------------------------- /arduino-board/parameters.h: -------------------------------------------------------------------------------- 1 | #ifndef PARAMETERS_H 2 | #define PARAMETERS_H 3 | 4 | #define SERIAL_BAUD 115200 // Baudrate 5 | #define MOTOR_PIN 3 6 | #define DIRECTION_PIN 4 7 | #define SERVOMOTOR_PIN 6 8 | #define INITIAL_THETA 110 // Initial angle of the servomotor 9 | // Min and max values for motors 10 | #define THETA_MIN 60 11 | #define THETA_MAX 150 12 | #define SPEED_MAX 100 13 | 14 | // If DEBUG is set to true, the arduino will send back all the received messages 15 | #define DEBUG false 16 | 17 | #endif 18 | -------------------------------------------------------------------------------- /arduino-board/slave.cpp: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | 4 | #include "order.h" 5 | #include "slave.h" 6 | #include "parameters.h" 7 | 8 | bool is_connected = false; ///< True if the connection with the master is available 9 | int8_t motor_speed = 0; 10 | int16_t servo_angle = INITIAL_THETA; 11 | Servo servomotor; 12 | 13 | void setup() 14 | { 15 | // Init Serial 16 | Serial.begin(SERIAL_BAUD); 17 | 18 | // Init Motor 19 | pinMode(MOTOR_PIN, OUTPUT); 20 | pinMode(DIRECTION_PIN, OUTPUT); 21 | // Stop the car 22 | stop(); 23 | 24 | // Init Servo 25 | servomotor.attach(SERVOMOTOR_PIN); 26 | // Order between 0 and 180 27 | servomotor.write(INITIAL_THETA); 28 | 29 | // Wait until the arduino is connected to master 30 | while(!is_connected) 31 | { 32 | write_order(HELLO); 33 | wait_for_bytes(1, 1000); 34 | get_messages_from_serial(); 35 | } 36 | 37 | } 38 | 39 | void loop() 40 | { 41 | get_messages_from_serial(); 42 | update_motors_orders(); 43 | } 44 | 45 | void update_motors_orders() 46 | { 47 | servomotor.write(constrain(servo_angle, THETA_MIN, THETA_MAX)); 48 | motor_speed = constrain(motor_speed, -SPEED_MAX, SPEED_MAX); 49 | // Send motor speed order 50 | if (motor_speed > 0) 51 | { 52 | digitalWrite(DIRECTION_PIN, LOW); 53 | } 54 | else 55 | { 56 | digitalWrite(DIRECTION_PIN, HIGH); 57 | } 58 | analogWrite(MOTOR_PIN, convert_to_pwm(float(motor_speed))); 59 | } 60 | 61 | void stop() 62 | { 63 | analogWrite(MOTOR_PIN, 0); 64 | digitalWrite(DIRECTION_PIN, LOW); 65 | } 66 | 67 | int convert_to_pwm(float motor_speed) 68 | { 69 | // TODO: compensate the non-linear dependency speed = f(PWM_Value) 70 | return (int) round(abs(motor_speed)*(255./100.)); 71 | } 72 | 73 | void get_messages_from_serial() 74 | { 75 | if(Serial.available() > 0) 76 | { 77 | // The first byte received is the instruction 78 | Order order_received = read_order(); 79 | 80 | if(order_received == HELLO) 81 | { 82 | // If the cards haven't say hello, check the connection 83 | if(!is_connected) 84 | { 85 | is_connected = true; 86 | write_order(HELLO); 87 | } 88 | else 89 | { 90 | // If we are already connected do not send "hello" to avoid infinite loop 91 | write_order(ALREADY_CONNECTED); 92 | } 93 | } 94 | else if(order_received == ALREADY_CONNECTED) 95 | { 96 | is_connected = true; 97 | } 98 | else 99 | { 100 | switch(order_received) 101 | { 102 | case STOP: 103 | { 104 | motor_speed = 0; 105 | stop(); 106 | if(DEBUG) 107 | { 108 | write_order(STOP); 109 | } 110 | break; 111 | } 112 | case SERVO: 113 | { 114 | servo_angle = read_i16(); 115 | if(DEBUG) 116 | { 117 | write_order(SERVO); 118 | write_i16(servo_angle); 119 | } 120 | break; 121 | } 122 | case MOTOR: 123 | { 124 | // between -100 and 100 125 | motor_speed = read_i8(); 126 | if(DEBUG) 127 | { 128 | write_order(MOTOR); 129 | write_i8(motor_speed); 130 | } 131 | break; 132 | } 133 | // Unknown order 134 | default: 135 | write_order(ERROR); 136 | write_i16(404); 137 | return; 138 | } 139 | } 140 | write_order(RECEIVED); // Confirm the reception 141 | } 142 | } 143 | 144 | 145 | Order read_order() 146 | { 147 | return (Order) Serial.read(); 148 | } 149 | 150 | void wait_for_bytes(int num_bytes, unsigned long timeout) 151 | { 152 | unsigned long startTime = millis(); 153 | //Wait for incoming bytes or exit if timeout 154 | while ((Serial.available() < num_bytes) && (millis() - startTime < timeout)){} 155 | } 156 | 157 | // NOTE : Serial.readBytes is SLOW 158 | // this one is much faster, but has no timeout 159 | void read_signed_bytes(int8_t* buffer, size_t n) 160 | { 161 | size_t i = 0; 162 | int c; 163 | while (i < n) 164 | { 165 | c = Serial.read(); 166 | if (c < 0) break; 167 | *buffer++ = (int8_t) c; // buffer[i] = (int8_t)c; 168 | i++; 169 | } 170 | } 171 | 172 | int8_t read_i8() 173 | { 174 | wait_for_bytes(1, 100); // Wait for 1 byte with a timeout of 100 ms 175 | return (int8_t) Serial.read(); 176 | } 177 | 178 | int16_t read_i16() 179 | { 180 | int8_t buffer[2]; 181 | wait_for_bytes(2, 100); // Wait for 2 bytes with a timeout of 100 ms 182 | read_signed_bytes(buffer, 2); 183 | return (((int16_t) buffer[0]) & 0xff) | (((int16_t) buffer[1]) << 8 & 0xff00); 184 | } 185 | 186 | int32_t read_i32() 187 | { 188 | int8_t buffer[4]; 189 | wait_for_bytes(4, 200); // Wait for 4 bytes with a timeout of 200 ms 190 | read_signed_bytes(buffer, 4); 191 | return (((int32_t) buffer[0]) & 0xff) | (((int32_t) buffer[1]) << 8 & 0xff00) | (((int32_t) buffer[2]) << 16 & 0xff0000) | (((int32_t) buffer[3]) << 24 & 0xff000000); 192 | } 193 | 194 | void write_order(enum Order myOrder) 195 | { 196 | uint8_t* Order = (uint8_t*) &myOrder; 197 | Serial.write(Order, sizeof(uint8_t)); 198 | } 199 | 200 | void write_i8(int8_t num) 201 | { 202 | Serial.write(num); 203 | } 204 | 205 | void write_i16(int16_t num) 206 | { 207 | int8_t buffer[2] = {(int8_t) (num & 0xff), (int8_t) (num >> 8)}; 208 | Serial.write((uint8_t*)&buffer, 2*sizeof(int8_t)); 209 | } 210 | 211 | void write_i32(int32_t num) 212 | { 213 | int8_t buffer[4] = {(int8_t) (num & 0xff), (int8_t) (num >> 8 & 0xff), (int8_t) (num >> 16 & 0xff), (int8_t) (num >> 24 & 0xff)}; 214 | Serial.write((uint8_t*)&buffer, 4*sizeof(int8_t)); 215 | } 216 | -------------------------------------------------------------------------------- /arduino-board/slave.h: -------------------------------------------------------------------------------- 1 | #ifndef ARDUINO_SLAVE_H 2 | #define ARDUINO_SLAVE_H 3 | 4 | /*! 5 | * \brief Send updated motors orders to the two motors (servomotor + motor) 6 | */ 7 | void update_motors_orders(); 8 | 9 | /*! 10 | * Stop the car (set the speed to 0) 11 | */ 12 | void stop(); 13 | 14 | /*! 15 | * \brief Convert a speed order (in percentage of max speed) 16 | * into a pwm order (between 0 and 255) 17 | * \param motor_speed speed order in percentage of max speed 18 | * \return the speed order in pwm 19 | */ 20 | int convert_to_pwm(float motor_speed); 21 | 22 | /*! 23 | * \brief Read one byte from the serial and cast it to an Order 24 | * \return the order received 25 | */ 26 | Order read_order(); 27 | 28 | /*! 29 | * \brief Wait until there are enough bytes in the buffer 30 | * \param num_bytes the number of bytes 31 | * \param timeout (ms) The timeout, time after which we release the lock 32 | * even if there are not enough bytes 33 | */ 34 | void wait_for_bytes(int num_bytes, unsigned long timeout); 35 | 36 | /*! 37 | * \brief Read signed bytes and put them in a buffer 38 | * \param buffer an array of bytes 39 | * \param n number of bytes to read 40 | */ 41 | void read_signed_bytes(int8_t* buffer, size_t n); 42 | 43 | /*! 44 | * \brief Read one byte from a serial port and convert it to a 8 bits int 45 | * \return the decoded number 46 | */ 47 | int8_t read_i8(); 48 | 49 | /*! 50 | * \brief Read two bytes from a serial port and convert it to a 16 bits int 51 | * \return the decoded number 52 | */ 53 | int16_t read_i16(); 54 | 55 | 56 | /*! 57 | * \brief Read four bytes from a serial port and convert it to a 32 bits int 58 | * \return the decoded number 59 | */ 60 | int32_t read_i32(); 61 | 62 | /*! 63 | * \brief Send one order (one byte) 64 | * \param order type of order 65 | */ 66 | void write_order(enum Order order); 67 | 68 | /*! 69 | * \brief Write one byte int to serial port (between -127 and 127) 70 | * \param num an int of one byte 71 | */ 72 | void write_i8(int8_t num); 73 | 74 | /*! 75 | * \brief Send a two bytes signed int via the serial 76 | * \param num the number to send (max: (2**16/2 -1) = 32767) 77 | */ 78 | void write_i16(int16_t num); 79 | 80 | /*! 81 | * \brief Send a four bytes signed int (long) via the serial 82 | * \param num the number to send (−2,147,483,647, +2,147,483,647) 83 | */ 84 | void write_i32(int32_t num); 85 | 86 | /*! 87 | * \brief Listen the serial and decode the message received 88 | */ 89 | void get_messages_from_serial(); 90 | 91 | #endif 92 | -------------------------------------------------------------------------------- /arduino-board/slave/order.h: -------------------------------------------------------------------------------- 1 | ../order.h -------------------------------------------------------------------------------- /arduino-board/slave/parameters.h: -------------------------------------------------------------------------------- 1 | ../parameters.h -------------------------------------------------------------------------------- /arduino-board/slave/slave.h: -------------------------------------------------------------------------------- 1 | ../slave.h -------------------------------------------------------------------------------- /arduino-board/slave/slave.ino: -------------------------------------------------------------------------------- 1 | ../slave.cpp --------------------------------------------------------------------------------