-
Notifications
You must be signed in to change notification settings - Fork 4
API documentation
Here you can find the Smartcar Sensors API documentation that will allow you to use the Smartcar Sensor library in order to easily control and read data from various sensors on the Smartcar. You can find the various accessible API components as well as usage examples. If you want to review how these components are used in a common sketch, please refer to the Example sketches section. Currently, the library supports the following sensors:
- The the HC-SR04 & SRF05 ultra sound sensors that measures distance.
- The SHARP GP2Y0A02 infrared sensor that measures distance.
You can use as many infra red and ultra sound sensors your development platform allows. They should all be running independently from each other. Moreover, when using the Arduino IDE, the available API components will be color-coded after being typed, which should help you acclimatize yourself and review code faster.
In order to start using the Smartcar Sensors library in your Arduino sketch, you have to include the _Smartcar Sensor library and the Wire library. You can achieve that in the standard C way, by using the #include statements like this:
#include <Smartcar_sensors.h>
#include <Wire.h>
The above lines must be written every time, if you want to use the Smartcar Sensors library.
The constructor of a Sonar instance, representing programmatically an ultra sound sensor that measures distance. You have to instantiate a Sonar in order to be able to control it. You should do this before your void setup() function in order for the instance variable to be globally accessible in your sketch and after the include statements. Don't forget that you can instantiate many sensors, as long as they are on different pins.
Example
#include <Smartcar_sensors.h>
#include <Wire.h>
Sonar rearSonar;
void setup(){
/* put your setup code here to run once */
}
void loop(){
/* your main loop code here to run repeatedly */
}
Always use this function first in the void setup() in order to initialize the Sonar and define the pins that it will be connected to, namely the echo pin and the trigger pin. Don't forget that you can attach many sensors as long as they are on different pins.
Example
#include <Smartcar_sensors.h>
#include <Wire.h>
Sonar rearSonar;
const int TRIG_PIN = 38; //sensor's trig pin
const int ECHO_PIN = 39; //sensor's echo pin
void setup(){
rearSonar.attach(TRIG_PIN, ECHO_PIN);
}
Get the distance measured by the specific ultra sound sensor in centimeters. The maximum distance that the ultra sound sensor can reliably measure in real life conditions is set to 150 centimeters. If a distance is out of range (either too close or too far away) 0 will be returned instead, as an indication of an error.
Example
int rearDistance = rearSonar.getDistance();
Get the median distance of the last 5 measurements by the specific ultra sound sensor, in centimeters. The maximum distance that the ultra sound sensor can reliably measure in real life conditions is set to 150 centimeters. If a distance is out of range (either too close or too far away) 0 will be returned instead, as an indication of an error. Expect a delay, between the measurements, of approximately 150 milliseconds when using this method. This is a simple and handy filter for the ultra sound sensor measurements.
Example
int rearDistance = rearSonar.getMedianDistance(); //get the median of the last 5 measurements
Get the median distance of the last iterations measurements by the specific ultra sound sensor, in centimeters. The maximum distance that the ultra sound sensor can reliably measure in real life conditions is set to 150 centimeters. If a distance is out of range (either too close or too far away) 0 will be returned instead, as an indication of an error. Expect a delay, between the measurements, of approximately 29 milliseconds for every iteration when using this method. This is a simple, flexible and handy filter for the ultra sound sensor measurements.
Example
int rearDistance = rearSonar.getMedianDistance(3); //get the median of the last 3 measurements
The constructor of a Sharp_IR instance, representing programmatically an SHARP infrared sensor that measures distance. You have to instantiate a Sharp_IR in order to be able to control it. You should do this before your void setup() function in order for the instance variable to be globally accessible in your sketch and after the include statements. Don't forget that you can instantiate many sensors, as long as they are on different analog pins.
Example
#include <Smartcar_sensors.h>
#include <Wire.h>
Sharp_IR frontIR;
const int IR_pin = A5; //use analog pin 5 to receive infra red's data
void setup(){
/* put your setup code here to run once */
}
void loop(){
/* your main loop code here to run repeatedly */
}
Always use this function first in the void setup() in order to initialize the Sharp_IR and define the analog pin that it will be connected to. Don't forget that you can attach many sensors as long as they are on different analog pins.
Example
#include <Smartcar_sensors.h>
#include <Wire.h>
Sharp_IR frontIR;
const int IR_pin = A5; //set analog pin 5 to receive infra red's data
void setup(){
frontIR.attach(IR_pin); //attach infra red sensor to IR_pin
}
Get the distance measured by the specific infra red sensor in centimeters. The maximum distance that the infra sound sensor can reliably measure in real life conditions is set to 80 centimeters, while minimum at 20 centimeters. If a distance is out of range (either too close or too far away) 0 will be returned instead, as an indication of an error.
Example
int frontDistance = frontIR.getDistance();
Get the median distance of the last 5 measurements by the specific infra red sensor, in centimeters. The maximum distance that the infra red sensor can reliably measure in real life conditions is set to 80 centimeters, while minimum at 20 centimeters. If a distance is out of range (either too close or too far away) 0 will be returned instead, as an indication of an error. Expect a delay, needed between the measurements, of approximately 75 milliseconds when using this method. This is a simple and handy filter for the infra red sensor measurements.
Example
int frontDistance = frontIR.getMedianDistance(); //get the median of the last 5 measurements
Get the median distance of the last iterations measurements by the specific infra red sensor, in centimeters. The maximum distance that the infra red sensor can reliably measure in real life conditions is set to 80 centimeters, while minimum at 20 centimeters. If a distance is out of range (either too close or too far away) 0 will be returned instead, as an indication of an error. Expect a delay, between the measurements, of approximately 15 milliseconds for every iteration when using this method. This is a simple and handy filter for the infra red sensor measurements.
Example
int frontDistance = frontIR.getMedianDistance(3); //get the median of the last 3 measurements
The constructor of an Odometer instance, representing programmatically an odometer (speed encoder) sensor that measures motor revolutions and thus an approximation of the traveled distance. You have to instantiate an Odometer in order to be able to read its data. You should do this before your void setup() function in order for the instance variable to be globally accessible in your sketch and after the include statements.
IMPORTANT
- You can only instantiate the odometer once. With limited modifications, the library can handle two (or more) encoders, if necessary.
- Connect the odometer data line only to interrupt pins! Find out which those are for your board here.
Example
#include <Smartcar_sensors.h>
#include <Wire.h>
Odometer encoder; //instantiate the odometer
void setup(){
/* put your setup code here to run once */
}
void loop(){
/* your main loop code here to run repeatedly */
}
Always use this function in order to initialize the Odometer and define the interrupt pin that it will be connected to. Don't forget that you can attach attach just one odometer and that only on an interrupt pin. If the pin is not a valid, then the function will return 0 to indicate an error, otherwise if everything works as it returns 1. Keep in mind that you do not necessarily have to do this during setup() and that that interrupt pin should not be used for other purposes as long the Odometer is attached.
Example
#include <Smartcar_sensors.h>
#include <Wire.h>
Odometer encoder;
const int encoderPin = 19; //digital pin 19 (interrupt 4 on arduino mega)
void setup(){
encoder.attach(encoderPin);
}
void loop(){
/* your main loop code here to run repeatedly */
}
Initiate a measurement by the Odometer. Call this function every time you want to start measuring the traveled distance of the Smartcar. Remember that you have to first attach(int odometerPin) the Odometer to a valid interrupt pin before you start measuring. If the Odometer is not attached then this function will have no effect. Moreover, if this function is omitted, then the measurement will begin from the last attach(int odometerPin), so it is strongly suggested to use this function for clarity.
Example
#include <Smartcar_sensors.h>
#include <Wire.h>
Odometer encoder;
const int encoderPin = 19; //digital pin 19 (interrupt 4 on arduino mega)
void setup(){
encoder.attach(encoderPin);
encoder.begin();
}
void loop(){
/* your main loop code here to run repeatedly */
}
Get the current traveled distance, in centimeters, since the beginning of the measurement. In other words since the last begin(). If begin() has been omitted, then you will get the distance since the last attach(int odometerPin), however this is not suggested for clarity reasons. If the Odometer is not attached or has been attached to an invalid (non-interrupt) pin, then this function will keep returning 0. The traveled distance has been empirically determined for the Smartcar platform and is set to 4 pulses per centimeter. If you are using a different set up, please adjust the value of the constant PULSES_PER_CENTIMETER in Smartcar_sensors.h
Example
#include <Smartcar_sensors.h>
#include <Wire.h>
Odometer encoder;
const int encoderPin = 19; //digital pin 19 (interrupt 4 on arduino mega)
void setup(){
Serial.begin(9600);
encoder.attach(encoderPin);
encoder.begin(); // begin measurement HERE
}
void loop(){
int traveledDistance = encoder.getDistance(); //get distance traveled since begin() in setup()
Serial.println(traveledDistance); // print the traveled distance
delay(200); //run the above every 200 milliseconds
}
Use this function in order to detach an Odometer from its assigned (interrupt) pin. Call this method in order to free the odometer pin, so it's no longer used by the Odometer and can be possibly used for different purposes or different sensors. After detaching an Odometer, getDistance() will keep returning 0 and begin() will have no effect. If you want to reattach an odometer, just call the attach(int odometerPin) method again.
Example
#include <Smartcar_sensors.h>
#include <Wire.h>
Odometer encoder;
const int encoderPin = 19; //digital pin 19 (interrupt 4 on arduino mega)
void setup(){
Serial.begin(9600);
encoder.attach(encoderPin);
encoder.begin(); // begin measurement HERE
delay(10000); //wait for 10 seconds (while the car is traveling)
int traveledDistance = encoder.getDistance(); //get distance traveled since begin()
Serial.println(traveledDistance); //print the traveled distance
encoder.detach();
delay(5000); //wait for 5 seconds (while the car keeps traveling)
traveledDistance = encoder.getDistance(); // traveledDistance = 0 !
Serial.println(traveledDistance); //will print 0
}
void loop(){
}
The constructor of a Gyroscope instance, representing programmatically a gyroscope, a sensor that measures angular velocity in X,Y,Z axis and thus an approximation of angular displacement. To put it simply, you can use a gyroscope to determine how much you have rotated. You have to instantiate an Gyroscope in order to be able to read its data. You should do this before your void setup() function in order for the instance variable to be globally accessible in your sketch and after the include statements.
IMPORTANT
- You can only instantiate the gyroscope once.
- Connect the gyroscope only only to SDA and SCL pins! Find out which those are for your board here.
- This method is currently not 100% safe to use concurrently with other I2C devices (Wire library). There might be errors.
- Always
stop()after you are done with a series of measurements, to release resources and to be able to use other I2C devices safely.
Example
#include <Smartcar_sensors.h>
#include <Wire.h>
Gyroscope gyro;
void setup() {
}
void loop() {
}
Always use this function in order to initialize the gyroscope and establish the connection to it. Don't forget that you can attach attach just one gyroscope and that only on the appropriate pins. Keep in mind that you do not necessarily have to do this during setup(). Finally, it is advised that you give it some time to set up the connection and get ready, with a delay of around 1.5 seconds.
Example
gyro.attach(); //initializes the gyroscope
delay(1500); //wait for it to get ready
Initiate a measurement by the Gyroscope. Call this function every time you want to start measuring the angular displacement (rotation) of the Smartcar. Remember that you always have to first attach() the Gyroscope before you start measuring. Generally you should avoid measuring angular displacement over long periods of time, due to errors accumulating in the result, so it is advised to begin() every time you want to initiate a measurement. Moreover, keep in mind that you should avoid measuring angular displacement when using other I2C devices as errors might occur.
Example
#include <Smartcar_sensors.h>
#include <Wire.h>
Gyroscope gyro;
void setup() {
gyro.attach(); //initializes the gyroscope
delay(1500); //wait for it to get ready
gyro.begin(); //start measuring angular displacement NOW
}
void loop() {
}
Get the current angular displacement, in degrees, since the beginning of the measurement. Negative values indicate counter clockwise rotation while positive clockwise. If you have different set up (orientation of gyroscope or different gyroscope model) you will have to adapt accordingly. This method will measure the angular displacement (rotation) since the last begin(). If begin() has been omitted, you will be receiving 0 as result, regardless of rotation. Keep in mind that the longer time has passed since the last begin() the less the accurate the results will be, due to error accumulation. Use begin() as often as you must in order to minimize the drift caused from errors.
Example
#include <Smartcar_sensors.h>
#include <Wire.h>
Gyroscope gyro;
void setup() {
gyro.attach(); //initializes the gyroscope
delay(1500); //wait for it to get ready
gyro.begin(); //start measuring angular displacement NOW
}
void loop() {
Serial.println(gyro.getAngularDisplacement()); //print angular displacement since begin()
delay(100); //delay for 100ms
}
Always use this method when you are done with a series of measurements, in order to free system resources and to be able to use other I2C devices safely. After you have used stop(), you need to use begin() in order to initiate a new measurement.
Example
#include <Smartcar_sensors.h>
#include <Wire.h>
Gyroscope gyro;
void setup() {
gyro.attach(); //initializes the gyroscope
delay(1500); //wait for it to get ready
gyro.begin(); //start measuring angular displacement NOW
}
void loop() {
delay(1000);
Serial.println(gyro.getAngularDisplacement()); //print angular displacement since begin() after approximately 1 second
gyro.stop();
Serial.println(gyro.getAngularDisplacement()); //will print 0 as will the first print out on the next loop
}