platisd / smartcar_shield

A versatile and easy to use vehicle platform for hobby-grade projects

Smartcar shield

A versatile and easy to use vehicle platform for hobby-grade projects

• Description
• Hardware
• Software
• Reference platforms
• How to get started
• Dependencies
• Project documentation
• License

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

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

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.

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 and a battery to them and a GY-50 gyroscope module (based on the L3G4200D sensor). In 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 which you can freely use in order to fabricate your own, e.g. with a milling machine or a laser cutter.

Emulator

SMCE is the digital twin of the Smartcar platform along with a cool and customisable 3D world for your rover to roam in.
The core concept is that you write Arduino code that runs on both the real hardware as well as the virtual environment. This way, the need to have exclusive and frequent access to the car can be either alleviated or drastically decreased. The emulator allows limiting the unavoidable engagement with the physical car, to the point a team of developers may develop their features on the emulator and only access the real hardware to verify them.

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 the various components (i.e. the vehicle and the various sensors) as objects, therefore enabling trivial control over the car's functions. The various operations exposed by the API, are thoroughly explained in API Documentation. You can find examples on how to use the library, in /examples.

The library is versatile and is independent from the shield or specific hardware. Particularly, its most important feature is that it supports multiple ways of steering and throttling with different types of motors. Moreover, it is possible to steer the vehicle by rotating the wheels on each side at a different speed, like a tank as well as by using a servo motor. Another option is to use a brushed DC motor for steering, a setup that is very common in cheap RC cars. Additionally, apart of the default brushed DC motors that are connected to the Smartcar shield, you can also use an electronic speed controller (ESC) in order to drive (throttle) the vehicle, using the very same library.

If the Smartcar shield library is installed through the Library Manager of Arduino IDE, as 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.

Reference platforms

Smartcar platform (default setup)

• 1 x Modules board (rev.2)
• 1 x Motor board (rev. 0)
• 4 x Brushed motors (530rpm @ 12V)
• 2 x TXS0108E TTL level shifters
• 1 x DOIT ESP32 devkit v1 (30 GPIO pins)
• 1 x TB6612FNG dual motor driver (Sparkfun)
• 4 x M6 (30mm) screws
• 4 x M6 nuts
• 16 x M3 (10mm) screws
• 16 x M3 nuts
• 2 x HSP 02052 Front Bumper
• 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 (30mm long)
• 4 x 8pin 2.54 pitch female pin headers
• 3 x 10KOhm resistors
• 8 x AA battery holders
• 1 x DD40AJSA adjustable buck converter
• 1 x SPDT switch
• 4 x VL45L0x ToF distance sensors (optional)
  • 4 x 4pin 2.54 angled headers to mount the sensors vertically

Smartcar shield

• Smartcar chassis
• Smartcar shield PCB
• L293D H-bridge
• GY-50 gyroscope module
• Two odometers (speed encoders) ([1] and [2] will suit commercially available chassis. [3] require some slight modifications)
• Male & female pin headers (optionally get stackable Arduino headers too)
• Five 2-pin screw terminals
• Pin jumper
• DIP16 socket
• 0.1uF capacitors (2)
• 100uF capacitor
• 9V or 12V battery pack (do not use a single 9V battery)

Supported sensors

• Distance sensors
  • Ultrasonic
    • HC-SR04
    • SRF08
  • Infrared
    • SHARP GP2D120
    • SHARP GP2Y0A02
    • SHARP GP2Y0A21
• Gyroscopes
  • GY-50 (L3G4200D)
• Odometers
  • Directional (4+ pins)
  • Non-directional (3-pins)

How to get started

• Assemble the vehicle
• Install the library
• Connect the motors appropriately (if using the shield)
• Getting started with the Smartcar Platform

Dependencies

All dependencies should be downloaded automatically by the Arduino IDE's library manager.

• Wire library
• Servo library
• ServoESP32
• ESP32 AnalogWrite

Project documentation

• API Documentation
• The Smartcar platform
• Wiki
• Turning software engineers into Makers

License

MIT

smartcar_shield's Issues

Fix code smells detected by Sonarqube

Description

Sonarqube has detected some code smells and the report can be found here.
Not all of them need to be fixed (i.e. ignore the ones about the commented-out code).

Definition of Done

• Fix the code smells
• Find ways (if any) to avoid regressions (e.g. through clang-tidy or compiler warnings)

Refactor 11 lines occurring 2 times in DistanceCar.cpp

I've selected for refactoring 11 lines of code which are duplicated in 1 file(s) (1, 2). Addressing this will make our codebase more maintainable and improve Better Code Hub's Write Code Once guideline rating! 👍

Here's the gist of this guideline:

• Definition 📖
  Do not copy code.
• Why❓
  When code is copied, bugs need to be fixed in multiple places. This is both inefficient and a source of regression bugs.
• How 🔧
  Avoid duplication by never copy/pasting blocks of code and reduce duplication by extracting shared code, either to a new unit or introduce a superclass if the language permits.

You can find more info about this guideline in Building Maintainable Software. 📖

---

ℹ️ To know how many other refactoring candidates need addressing to get a guideline compliant, select some by clicking on the 🔲 next to them. The risk profile below the candidates signals (✅) when it's enough! 🏁

---

Good luck and happy coding! ✨ 💯

Fix compilation of gMock failing on CI

Description

GMock compilation on CI seems to have started failing.
An easy fix is to remove the pedantic flag when GMock is being compiled. It shouldn't matter since it's an external library.

Definition of Done

• All CI jobs are 🟢 again.

Use composition instead of inheritance for Odometer classes

Description

Currently DirectionalOdometer is extending DirectionlessOdometer so to utilize some common functionality. However, a DirectionalOdometer is not a DirectionlessOdometer. Both are Odometers that are using an Encoder.

Definition of Done

DirectionalOdometer is no more inheriting from a concrete class and there's little to no code duplication.

Remove ArduinoRuntime hack

Description

Static instantiation of the ArduinoRuntime in Smartcar.h so it can be used as a conditional statement in different class constructors should be removed, as well as the default argument.

It seems that library users are starting off by copying the examples anyway, so it won't be too cumbersome.

Definition of Done

• Smartcar.h does not instantiate an ArduinoRuntime instance, that is left for the user to do.
• Default runtime argument is removed from the constructors that use it.

Minsumo hardware supported?

Description

This Minisumo robot project https://github.com/hansj66/micro-bot/#readme has similar hardware II think L293DD is supported under your library?

Assuming the Micro:Bit slot had an ESP32 device inserted would you anticipate any problems getting it to run?

If there are no obvious problems I might do a version with hall encoders

Definition of Done

Disabling Cruise Control

The method disableCruiseControl(); method isn't being recognised by the Arduino IDE.

Migrate CI to GitHub actions

Description

Currently we are using TravisCI for continuous integration. Travis CI downloads an IDE to compile the sketches which can be finicky as it has not been made with command line usage in mind.
Let's move to GitHub which is using arduino-cli instead that seems to be the new thing that should catch on.

Definition of Done

TravisCI functionality is migrated over to GitHub Actions.

Add support for MPU-6050

Would you be able to add support for the MPU-6050 board ( GY-521 gyroscope module ) in addition to the existing MPU-3050 (GY-50 gyroscope module)?

Cheers
Douglas

Refactor 6 lines occurring 2 times in SRF08.cpp

I've selected for refactoring 6 lines of code which are duplicated in 1 file(s) (1, 2). Addressing this will make our codebase more maintainable and improve Better Code Hub's Write Code Once guideline rating! 👍

Here's the gist of this guideline:

• Definition 📖
  Do not copy code.
• Why❓
  When code is copied, bugs need to be fixed in multiple places. This is both inefficient and a source of regression bugs.
• How 🔧
  Avoid duplication by never copy/pasting blocks of code and reduce duplication by extracting shared code, either to a new unit or introduce a superclass if the language permits.

You can find more info about this guideline in Building Maintainable Software. 📖

---

ℹ️ To know how many other refactoring candidates need addressing to get a guideline compliant, select some by clicking on the 🔲 next to them. The risk profile below the candidates signals (✅) when it's enough! 🏁

---

Good luck and happy coding! ✨ 💯

getSpeed and GetDirection

As there are DCMotors::setSpeed and DCMotors::setAngle methods, would it be possible to have DCMotors::getSpeed and DCMotors::getAngle methods as well to enable the code to determine where the robot is heading?

Cheers
Douglas

CI build is broken due to esp8266 package.json missing

Description

At the moment, the esp8266 package is not available which causes the build to fail as it cannot compile the examples against the esp8266 board.

Definition of Done

• Retrigger the build once esp8266/Arduino#5664 is fixed or the website comes back up.

Cruise control suffers from runaway due to temporary sensor failure

The cruise control functionality of the library can cause runaway as a result of a temporary sensor failure. As a consequence, the controlled rover moves in the direction opposite to the requested one at maximum speed.

The problem affects the cruise control functionality enabled using car.enableCruiseControl(). We observed it with this rover type.

The problem manifests when the rover is commanded to drive forward, but is still standing and the odometers temporarily report high moving speed due to signal transmission failure. The controller will then apply negative torque (meant for braking), which accelerates the rover backwards. As the rover accelerates backwards, the odometers correctly report increasing speed (the odometers report the absolute speed, not the direction), which is interpreted as the rover moving forward too fast. This results in more negative torque being applied, and a complete runaway with the rover racing backwards.

The following sketch can be used to demonstrate the problem.

#include <Smartcar.h>

Odometer encoderLeft(188), encoderRight(188);
Gyroscope gyro(22);
Car car;

const int encoderLeftPin = 2;
const int encoderRightPin = 3;
const float fSpeed = 0.3; //a ground speed (m/sec) for going forward
bool sw = false;

void setup() {
  Serial3.begin(9600);
  encoderLeft.attach(encoderLeftPin);
  encoderRight.attach(encoderRightPin);
  gyro.attach();
  delay(1500);
  gyro.begin(60);
  encoderLeft.begin();
  encoderRight.begin();
  car.begin(encoderLeft, encoderRight, gyro); //initialize the car using the encoders
  car.enableCruiseControl(); //using default PID values
  car.setAngle(0);
 // car.enableCruiseControl(12,5,17,30); //using custom values and control frequency
  car.setSpeed(fSpeed);
}

void loop() {
  car.updateMotors();
  handleInput();
}

int state = 0;

void handleInput() {
  int t = millis();
  if (t >= 1000 && state < 1) {
    car.setSpeed(fSpeed);
    state = 1;
  } else if (t >= 3000 && state < 2) {
    car.setSpeed(0);
    state = 2;
  }

}

The sketch uses the cruise control functionality, requesting to drive forward at 1 s after setup, and then stopping at 3 s. The correct behaviour with the sketch is the rover driving forward and then stopping.

We managed to trigger erroneous behaviour by using the rover with depleted batteries. With that setup, the rover will occasionally race backwards instead of moving forward. We observed incorrect behaviour once every 4 attempts or so, but this probability is greatly dependent on the state of the batteries. We also observed it by using an incomplete battery pack (6 1.5 V batteries instead of 8), giving the measured voltage 8.4 V dropping to 6.4 V under load (we could not measure voltage under load reliably due to how fast was changing). Connecting the Arduino board to USB power makes the problem go away completely.

We traced the problems to the odometers returning high speeds temporarily when the rover is standing or moving slowly. We don’t know what causes the incorrect readouts. We suspect that the voltage ripple from the motor controller is interpreted as signal edges from the odometers.

We believe that the cause of the incorrect readouts should be investigated, but the fundamental problem here is that the control turns a small disturbance (or input corruption) into a complete runaway. Using odometers that also report the direction of movement in addition to the speed would solve the problem. With the current odometers, the controller should be somehow constrained to avoid the runaway.

Motor driver abstraction

Description

This lib seems to do a nice job of abstracting motor drivers: https://github.com/tfeldmann/Arduino-MotorDriver

Could you provide some example code for how you would integrate that with your library?

Definition of Done

It's clear how to use various types of motor driver with the Smartcar_shield library.

support servo drivemotor?

Description

Does this lib support servos as drive motors?

Definition of Done

This chassis works using just esp32 and 5v power source

https://m.aliexpress.com/item/32607362464.html

supported IMU/ motor driver list

Description

Is there a list of supported IMU anywhere? Or is it just the GY50?

I'd be particularly interested in any of the breakout garden IMU?
https://shop.pimoroni.com/collections/breakout-garden?q=robot

Definition of Done

Documentation includes list of supported hardware, or clarifies rhat it is only GY50 that is supported

Arduino lib for additional IMU

Description

Support additional common IMU

Definition of Done

Add support the IMU supported by this Arduino Lib: https://github.com/torehan/arduino-mpu-driver/blob/master/src/MPU.cpp#L153

Fix doxygen publication GitHub Action

Description

Seems like it's broken.

Definition of Done

Job is again 🟢

Web interface?

Description

Would you be interested in adding a web interface like this: https://github.com/701lab/ESP32-robot-car-controller#esp32-robot-car-controller

To your library? It seems like it should be possible: 701lab/ESP32-robot-car-controller#2 (comment)

Definition of Done

BNO055?

Description

Add support for https://github.com/adafruit/Adafruit_BNO055

Various open hardware boards are available:
https://www.smart-prototyping.com/Zio-9DOF-IMU-BNO055.html
https://www.adafruit.com/product/4646

If I post you one would you have a go at getting it working?

Definition of Done

Be standard C++: get rid of VLAs

Description

Library uses VLAs hence is not C++ compliant, making it not compile on compliant compilers

Implementation

Replace by fixed-size buffers

Definition of Done

Library does not use VLAs and documentation reflects changes

Enforce SmarterCar architecture

Enforce the software architecture as defined by SmarterCar project, in order to improve the OO design of the library and increase its modularity and consistency.

DRV8830

Description

Would you be interested in supporting https://github.com/adafruit/Adafruit_DRV8830 under your library?

Definition of Done

Remove unintended Arduino dependencies from Runtime interface

Description

The Runtime interface is supposed to be a platform agnostic representation of the
runtime environment.
Instead of passing arbitrary numbers (which will only work for Arduino), we should
instead pass generic enums and let each implementation determine how these
enums should be interpreted.

Definition of Done

• Platform specific dependencies are removed