Smartcar library version 6.0.0 (#18)

After the Smartcar got upgraded with an ESP32 at its core, several compatibility
changes were necessary to the library. Specifically, ESP32 does not natively support
the Servo library and has no analogWrite method. External libraries were chosen
to fill this gap and other several compatibility enhancements were made to ensure
that the differences between the AVR microcontrollers and ESP32 are transparent
to the user.

Additionally, the Odometer constructors were updated to eliminate any sequential
coupling and enforce a more RAII way of doing things.

Finally, several other smaller improvements and refinements are introduced.

Author: platisd

.gitignore

@@ -16,3 +16,6 @@ static-analysis-report/
 arduino*.xz
 coverage-reports
 coverage.info
+
+# Ignore vscode configuration
+.vscode

.travis.yml

@@ -1,24 +1,21 @@
-# Set language to `none` because if set to `cpp` CXX and C environment variables
-# are overriden with those of older versions
-language: none
-
-env:
-    global:
-        - CXX=g++-5
+language: cpp
+dist: bionic
 
 addons:
     apt:
+        update: true
         sources:
-            - ubuntu-toolchain-r-test
+            - sourceline: "ppa:ubuntu-toolchain-r/test"
         packages:
-            - g++-5
+            - g++
             - lcov
             - doxygen
             - doxygen-doc
             - doxygen-latex
             - doxygen-gui
             - graphviz
             - cppcheck
+            - clang-tidy-8
 
 notifications:
     email: false
@@ -35,17 +32,22 @@ cache:
 before_install:
   # Set up the environment for building with the Arduino IDE
   - source <(curl -SLs https://raw.githubusercontent.com/adafruit/travis-ci-arduino/master/install.sh)
+install:
+  - arduino --install-library "ESP32 AnalogWrite"
+  - arduino --install-library "ServoESP32"
 
 script:
     # Build and run unit tests
     - bash test/build_and_run_ut.sh
     # Run static code analysis over the source code
     - cppcheck --std=c++11 --enable=performance,portability,information --quiet --error-exitcode=1 src/
+    - bash run_clang-tidy.sh
     # Ensure examples are buildable for various boards
     - build_platform uno
     - build_platform mega2560
     - build_platform leonardo
     - build_platform esp8266
+    - build_platform esp32
 
 after_success:
     - bash run_coverage.sh

README.md

@@ -5,38 +5,66 @@ A versatile and easy to use vehicle platform for hobby-grade projects
 * [Description](#description)
 * [Hardware](#hardware)
 * [Software](#software)
-* [Materials needed](#materials-needed-default-setup)
+* [Reference platforms](#reference-platforms)
 * [Supported sensors](#supported-sensors)
 * [How to get started](#how-to-get-started)
 * [Dependencies](#dependencies)
 * [Extensions](#extensions)
 * [Project documentation](#project-documentation)
 * [License](#license)
 
-### Description
+## Description
 This repository, includes everything necessary to set up a Smartcar platform.
 The Smartcar, is a vehicular educational platform, which enables the user to develop
 various robotic applications in an affordable, pedagogic and easy way. It is intended
 for persons with basic programming knowledge and little to no experience of electronics,
 mechanics or robotics. More experienced users, should also find this approach convenient,
 due to its open source nature, high level API and object oriented design.
 
-### Hardware
-The platform, hardware wise is conceptually focused around the Smartcar shield. The Smartcar
-shield is an open hardware PCB, that is effortlessly stacked on top of an Arduino. It includes
-an L293D H-bridge chip, that drives the motors, screw terminals to connect the motors
+## Hardware
+Despite the software being hardware-agnostic, historically, development has been based on specific
+hardware. Initially, the **Smartcar shield** was used on top of an Arduino, using cheap car kits.
+This setup will be referred to as `shield` or `v1`.
+
+Since the winter of 2019, a new platform was developed from scratch, using the WiFi and Bluetooth
+enabled ESP32 as the vehicle's "brain". This setup will be referred to as `platform` or `v2` and
+will be considered the default one from now on. It offers greater robustness and many more
+possibilities, as it offers out-of-the-box connectivity.
+
+### Platform
+
+![smartcar platform](https://i.imgur.com/cFrq2Wj.jpg)
+
+The Smartcar platform is a complete hardware solution for your hobby-grade, connected vehicle project.
+It is comprised of the chassis, made out of printed circuit boards, stacked on each other and an
+ESP32 development board that drives the motors, controls the sensors and communicates with the
+world via WiFi and Bluetooth.
+
+There are 4 motors with directional odometers which enable not only to determine how much the
+wheels have moved but also the direction they spin. It is equipped with a GY-50 gyroscope module
+(based on the L3G4200D sensor) to provide heading information and sockets to optionally connect
+4 `VL45L0X` LIDAR sensors to provide distance measurements. It is powered up by 8 AA batteries
+and you can find the boards' source files in [extras/eagle/smartcar_platform](/extras/eagle/smartcar_shield).
+
+### Shield
+
+![smartcar_shield](https://i.imgur.com/7g5ts49.png)
+
+The Smartcar shield is an open hardware PCB, that is effortlessly stacked on top of an Arduino. It
+includes an L293D H-bridge chip, that drives the motors, screw terminals to connect the motors
 and a battery to them and a GY-50 gyroscope module (based on the L3G4200D sensor).
 In [extras/eagle/smartcar_shield](/extras/eagle/smartcar_shield) you can find the
 design files for the board, in a modifiable form, using free software. There are
 also the options, to order it as-is, from either USA or China based manufacturers.
+
 The Smartcar shield, facilitates efficient cable management, helps to preserve space
 and is as small as possible, in order to keep the manufacturing price low. Additionally,
 the components necessary to assemble it, are widely available over the Internet. Furthermore,
 you can find 2D CAD drawings of the Smartcar chassis in various formats, at
 [/extras/cad/2D](extras/cad/2D) which you can freely use in order to fabricate your own,
 e.g. with a milling machine or a laser cutter.
 
-### Software
+## Software
 The software, is the Smartcar shield Arduino library. It sports a high level API, meant to
 enable its users to perform tasks easily with relatively few lines of code. It intends to
 hide implementation details or low level hardware operations. The library, handles
@@ -58,7 +86,34 @@ If the Smartcar shield library is installed through the Library Manager of Ardui
 recommended, the user will receive a notification in their IDE, when new versions are released
 making updates particularly easy, without the need to use GitHub or git.
 
-### Materials needed (default setup)
+## Reference platforms
+
+### Smartcar platform (default setup)
+
+* 1 x [Modules board](https://www.pcbway.com/project/shareproject/Smartcar___Module_board.html)
+* 1 x [Motor board](https://www.pcbway.com/project/shareproject/Smartcar___Motors_board.html)
+* 4 x [Brushed motors](https://www.aliexpress.com/item/32872592243.html?spm=a2g0s.9042311.0.0.40d44c4dvsYt5w)
+* 2 x [TTL level shifters](https://www.aliexpress.com/item/32472491036.html?spm=a2g0s.9042311.0.0.40d44c4dvsYt5w)
+* 1 x DOIT ESP32 devkit v1 (30 GPIO pins)
+* 1 x [TB6612FNG dual motor driver (Sparkfun)](https://www.sparkfun.com/products/14451)
+* 4 x M6 (30mm) screws
+* 4 x M6 nuts
+* 16 x M3 (10mm) screws
+* 16 x M3 nuts
+* 2 x [HSP 02052 Front Bumper](https://www.aliexpress.com/item/32753903115.html)
+* 10 x 6pin 2.54 pitch female pin headers
+* 2 x 15pin 2.54 pitch female pin headers
+* 1 x GY-50 gyroscope
+* 4 x [8pin 2.54 pitch long male pin headers](https://www.aliexpress.com/item/32911455899.html) (30mm long)
+* 4 x 8pin 2.54 pitch female pin headers
+* 3 x 10KOhm resistors
+* 8 x [AA battery holders](https://www.electrokit.com/produkt/batterihallare-1xaa-pcb/)
+* 1 x [DD40AJSA adjustable buck converter](https://www.aliexpress.com/item/32816584868.html) 
+* 4 x [VL45L0x ToF distance sensors](https://www.aliexpress.com/item/32828144370.html) (optional)
+  * 4 x 4pin 2.54 angled headers to mount the sensors vertically
+
+### Smartcar shield
+
  * Smartcar chassis
  * [Smartcar shield PCB](extras/eagle/smartcar_shield)
  * L293D H-bridge
@@ -91,25 +146,25 @@ making updates particularly easy, without the need to use GitHub or git.
    * Directional (4+ pins)
    * Non-directional (3-pins)
 
-### How to get started
+## How to get started
  * Assemble the vehicle
  * [Install the library](https://www.ardu-badge.com/Smartcar%20shield)
- * [Connect the motors appropriately](examples/Car/shieldMotorsTest/shieldMotorsTest.ino) (if using the default setup)
+ * [Connect the motors appropriately](examples/Car/shieldMotorsTest/shieldMotorsTest.ino) (if using the shield)
  * [Getting started with the Smartcar Platform](https://www.hackster.io/platisd/getting-started-with-the-smartcar-platform-1648ad)
 
-### Dependencies
-- [Wire library](http://arduino.cc/en/reference/Wire) (included with the Arduino IDE)
-- [Servo library](https://www.arduino.cc/en/reference/servo) (included with the Arduino IDE)
+## Dependencies
+All dependencies should be downloaded automatically by the Arduino IDE's library manager.
 
-### Extensions
-You can utilize the object oriented design of this library in order to easily extend it.
-Have a look at the [Library Architecture](../../wiki/Library-architecture).
+- [Wire library](http://arduino.cc/en/reference/Wire)
+- [Servo library](https://www.arduino.cc/en/reference/servo)
+- [ServoESP32](https://github.com/RoboticsBrno/ServoESP32)
+- [ESP32 AnalogWrite](https://github.com/ERROPiX/ESP32_AnalogWrite)
 
-### Project documentation
+## Project documentation
 * [API Documentation](https://platisd.github.io/smartcar_shield/)
 * [The Smartcar platform](http://plat.is/smartcar)
-* [Wiki](../../wiki)
+* [Wiki](https://github.com/platisd/smartcar_shield/wiki)
 * [Turning software engineers into Makers](https://platis.solutions/blog/2016/06/17/turning-software-engineers-into-makers/)
 
-### License
+## License
 MIT

examples/Car/DistanceCar/DistanceCar.ino

@@ -1,34 +1,30 @@
 #include <Smartcar.h>
 
-const unsigned short LEFT_ODOMETER_PIN = 2;
-const unsigned short RIGHT_ODOMETER_PIN = 3;
-
-BrushedMotor leftMotor(8, 10, 9);
-BrushedMotor rightMotor(12, 13, 11);
+BrushedMotor leftMotor(smartcarlib::pins::v2::leftMotorPins);
+BrushedMotor rightMotor(smartcarlib::pins::v2::rightMotorPins);
 DifferentialControl control(leftMotor, rightMotor);
 
-DirectionlessOdometer leftOdometer(100);
-DirectionlessOdometer rightOdometer(100);
+const auto pulsesPerMeter = 600;
 
-DistanceCar car(control, leftOdometer, rightOdometer);
+DirectionlessOdometer leftOdometer(
+    smartcarlib::pins::v2::leftOdometerPin, []() { leftOdometer.update(); }, pulsesPerMeter);
+DirectionlessOdometer rightOdometer(
+    smartcarlib::pins::v2::rightOdometerPin, []() { rightOdometer.update(); }, pulsesPerMeter);
 
-void setup() {
-  // Initialize the odometers (they won't work otherwise)
-  leftOdometer.attach(LEFT_ODOMETER_PIN, []() {
-    leftOdometer.update();
-  });
-  rightOdometer.attach(RIGHT_ODOMETER_PIN, []() {
-    rightOdometer.update();
-  });
+DistanceCar car(control, leftOdometer, rightOdometer);
 
-  car.enableCruiseControl();
-  car.setSpeed(1.5); // Maintain a speed of 1.5 m/sec
+void setup()
+{
+    car.enableCruiseControl();
+    car.setSpeed(1.5); // Maintain a speed of 1.5 m/sec
 }
 
-void loop() {
-  car.update(); // Maintain the speed
-  // Stop after moving 1 meter
-  if (car.getDistance() >= 100) {
-    car.setSpeed(0);
-  }
+void loop()
+{
+    car.update(); // Maintain the speed
+    // Stop after moving 1 meter
+    if (car.getDistance() >= 100)
+    {
+        car.setSpeed(0);
+    }
 }

examples/Car/FullSerialControl/FullSerialControl.ino

@@ -1,29 +1,37 @@
 #include <Smartcar.h>
 
-BrushedMotor leftMotor(8, 10, 9);
-BrushedMotor rightMotor(12, 13, 11);
+BrushedMotor leftMotor(smartcarlib::pins::v2::leftMotorPins);
+BrushedMotor rightMotor(smartcarlib::pins::v2::rightMotorPins);
 DifferentialControl control(leftMotor, rightMotor);
 
 SimpleCar car(control);
 
-void setup() {
-  Serial.begin(9600);
-  Serial.setTimeout(200);
+void setup()
+{
+    Serial.begin(9600);
+    Serial.setTimeout(200);
 }
 
-void loop() {
-  handleInput();
+void loop()
+{
+    handleInput();
 }
 
-void handleInput() { //handle serial input if there is any
-  if (Serial.available()) {
-    String input = Serial.readStringUntil('\n');
-    if (input.startsWith("m")) {
-      int throttle = input.substring(1).toInt();
-      car.setSpeed(throttle);
-    }else if (input.startsWith("t")){
-      int deg = input.substring(1).toInt();
-      car.setAngle(deg);
+void handleInput()
+{
+    // handle serial input if there is any
+    if (Serial.available())
+    {
+        String input = Serial.readStringUntil('\n');
+        if (input.startsWith("m"))
+        {
+            int throttle = input.substring(1).toInt();
+            car.setSpeed(throttle);
+        }
+        else if (input.startsWith("t"))
+        {
+            int deg = input.substring(1).toInt();
+            car.setAngle(deg);
+        }
     }
-  }
 }

examples/Car/HeadingCar/HeadingCar.ino

@@ -1,27 +1,30 @@
 #include <Smartcar.h>
 
-const int GYROSCOPE_OFFSET = 37;
+const int GYROSCOPE_OFFSET         = 37;
 const unsigned long PRINT_INTERVAL = 100;
-unsigned long previousPrintout = 0;
+unsigned long previousPrintout     = 0;
 
-BrushedMotor leftMotor(8, 10, 9);
-BrushedMotor rightMotor(12, 13, 11);
+BrushedMotor leftMotor(smartcarlib::pins::v2::leftMotorPins);
+BrushedMotor rightMotor(smartcarlib::pins::v2::rightMotorPins);
 DifferentialControl control(leftMotor, rightMotor);
 
 GY50 gyroscope(GYROSCOPE_OFFSET);
 
 HeadingCar car(control, gyroscope);
 
-void setup() {
-  Serial.begin(9600);
+void setup()
+{
+    Serial.begin(9600);
 }
 
-void loop() {
-  // Update the heading readings
-  car.update();
-  unsigned long currentTime = millis();
-  if (currentTime >= previousPrintout + PRINT_INTERVAL) {
-    previousPrintout = currentTime;
-    Serial.println(car.getHeading());
-  }
+void loop()
+{
+    // Update the heading readings
+    car.update();
+    unsigned long currentTime = millis();
+    if (currentTime >= previousPrintout + PRINT_INTERVAL)
+    {
+        previousPrintout = currentTime;
+        Serial.println(car.getHeading());
+    }
 }