ROVER - Rover API Base added
Signed-off-by: Mustafa Ozcelikors <mozcelikors@gmail.com>
diff --git a/rover/include/roverapi/rover_api.hpp b/rover/include/roverapi/rover_api.hpp
new file mode 100644
index 0000000..2030d15
--- /dev/null
+++ b/rover/include/roverapi/rover_api.hpp
@@ -0,0 +1,327 @@
+/*
+ * Copyright (c) 2017 FH Dortmund and others
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Description:
+ * Rover API - Interfaces for Rover application development - Header file
+ *
+ * Contributors:
+ * M.Ozcelikors <mozcelikors@gmail.com>, created API 17.11.2017
+ *
+ */
+
+#ifndef ROVER_API_HPP_
+#define ROVER_API_HPP_
+
+#include <stdint.h>
+
+#include <roverapi/rover_display.hpp>
+#include <roverapi/rover_driving.hpp>
+#include <roverapi/rover_gpio.hpp>
+#include <roverapi/rover_sensors.hpp>
+#include <roverapi/rover_utils.hpp>
+#include <roverapi/rover_cloud.hpp>
+
+/**
+\mainpage Rover API Main Page
+
+\section api_info roverapp and Rover API Info
+
+Rover software, called **roverapp** features a multi-threaded (POSIX threads or Pthreads) C/C++ implementation that runs on Linux-based embedded single board computers (such as Raspberry Pi).
+Rover features countless threads dedicated to communication infrastructure, sensor driving, display unit (such as OLED displays) utilization, bluetooth communication, image processing, and behavior modes (such as Parking, Adaptive Cruise Control, Manual Driving, and Booth Modes).
+It also features drivers for sensors such as magnetometers, accelerometers, various ultrasonic sensors, and camera modules. Furthermore, OLED display, buttons, a buzzer are utilized.
+
+Roverapp builds and contains the **Rover API**, which is able to handle subset of its functionality. Example functionality covered in **Rover API** is given below:
+
+\li **RoverBase** class is the main class used for instantiating rover objects.
+Each RoverBase object has private member functions referencing to other API classes exclusive to one RoverBase object.
+Therefore, using one RoverBase class, other classes can be accessed, and operations such as initialization,
+shutting down could be performed.
+\li **RoverCloud** contains the member functions to connect and send data to Eclipse Hono instance using several parameters such as host name, port, tenant name, user name, and password. This class wraps hono_interaction library for Rover-specific interactions.
+\li **RoverDisplay** contains the member functions to control OLED display on the Rover. This class is a wrapper API for Adafruit_GFX and Adafruit_SSD1306 libraries.
+\li **RoverDriving** contains the member functions to drive the rover using its motors.
+\li **RoverGpio** class provides the member functions related to embedded buzzer, user button, and shutdown button on the rover.
+\li **RoverSensors** class contains member functions to setup and read from embedded sensors from rover's RoverSenseLayer sensor layer.
+\li **RoverUtils** contains member functions to retrieve connectivity status and core utilization of the rover. This class wraps status_library lib, developed for the rover-app.
+
+\image html ./images/rover2.jpg
+
+\section example_usage Rover API Example Usage
+The following is an example C++ application using some of the Rover API functions:
+
+\code{.cpp}
+#include <roverapi/rover_api.hpp>
+
+using namespace rover;
+
+int main (void)
+{
+ RoverBase r;
+
+ // Initialize all components of the rover
+ r.initialize();
+ // or use r.initializeRoverSensors(), r.initializeRoverDisplay(), r.initializeRoverDriving(), r.initializeRoverGpio() to initialize individual components
+
+ // Set-up cloud instance and register your device
+ RoverCloud r_cloud = r.inRoverCloud();
+
+ r_cloud.setHono("localhost", 8080, "DEFAULT_TENANT");
+
+ r_cloud.setRegistrationPort(28080);
+
+ if (r_cloud.registerDevice("4711") == 1)
+ {
+ printf ("Registered device to Hono cloud using REST API successfully..\n");
+ }
+
+ // Send telemetry data to Hono instance
+ if (r_cloud.sendTelemetry("4711","myuser","mypassword","roverFront", 100.0) == 1)
+ {
+ printf ("Data sent to Hono cloud using REST API successfully..\n");
+ }
+
+ // Driving with rover
+ r.inRoverDriving().setSpeed(r.inRoverDriving().HIGHEST_SPEED);
+ r.inRoverDriving().goForward();
+ r.sleep (500); // Sleep for some time in milliseconds
+ r.inRoverDriving().turnRight();
+ r.sleep (500); // Sleep for some time in milliseconds
+ r.inRoverDriving().stopRover();
+
+
+ // Accessing sensors with rover
+ RoverSensors r_sensors = r.inRoverSensors();
+
+ printf ("Ultrasonic = [%d %d]\n", r_sensors.readHCSR04UltrasonicSensor(r_sensors.ROVER_FRONT),
+ r_sensors.readHCSR04UltrasonicSensor(r_sensors.ROVER_REAR));
+ printf ("Infrared = [%f %f %f %f]\n", r_sensors.readInfraredSensor(r_sensors.ROVER_FRONT_LEFT),
+ r_sensors.readInfraredSensor(r_sensors.ROVER_FRONT_RIGHT),
+ r_sensors.readInfraredSensor(r_sensors.ROVER_REAR_LEFT),
+ r_sensors.readInfraredSensor(r_sensors.ROVER_REAR_RIGHT));
+ printf ("Temperature = %f\n", r_sensors.readTemperature());
+ printf ("Humidity = %f\n", r_sensors.readHumidity());
+ printf ("Bearing = %f\n", r_sensors.readBearing());
+
+ // Checking if a button is pressed (LOW) and playing a tone with buzzer
+ if (r.inRoverGpio().readUserButton() == r.inRoverGpio().LO)
+ {
+ r.inRoverGpio().setBuzzerFrequency(400); //in Hz
+ r.inRoverGpio().setBuzzerOn();
+ r.sleep(1000);
+ }
+ r.inRoverGpio.setBuzzerOff();
+
+ // Print core utilization from the rover's OS
+ float *util = r.inRoverUtils.getCoreUtilization();
+ printf ("Utilization = [%f %f %f %f]\n", util);
+
+ // Use the OLED display on the rover
+ RoverDisplay my_display = r.inRoverDisplay();
+
+ // Prepare display contents
+ my_display.clearDisplay();
+ my_display.setTextSize(2);
+ my_display.setTextColor(my_display.WHITE_COLOR);
+
+ my_display.setCursor(12,10);
+ my_display.print("INTERNET:");
+
+ my_display.setTextSize(3);
+ my_display.setTextColor(my_display.WHITE_COLOR);
+
+ // Check if internet is connected
+ if (r.inRoverUtils().getInternetStatus() == 1)
+ {
+ my_display.setCursor(50,32);
+ my_display.print("ON");
+ }
+ else
+ {
+ my_display.setCursor(43,32);
+ my_display.print("OFF");
+ }
+
+ // Display now
+ my_display.display();
+
+ // Sleep a bit
+ r.sleep(5000);
+
+ // Shutdown the rover OS and abort the application
+ r.shutdown();
+
+ return 1;
+}
+\endcode
+
+\section roverdocs Rover Documentation
+
+Link: <a href="http://app4mc-rover.github.io/rover-docs">Rover Complete Documentation</a>
+
+\copyright Copyright(C) 2017 IDiAL Institute, Fachhochschule Dortmund
+
+*/
+
+/**
+ * @brief rover Namespace contains classes to manage Rover sensors, gpio, driving, utilities, and cloud.
+ */
+namespace rover
+{
+ /**
+ * @brief RoverBase class is the main class used for instantiating rover objects.
+ * Each RoverBase object has private member functions referencing to other API classes exclusive to one RoverBase object.
+ * Therefore, using one RoverBase class, other classes can be accessed, and operations such as initialization,
+ * shutting down could be performed.
+ */
+ class RoverBase
+ {
+ private:
+ /**
+ * @brief Private RoverCloud instance that is accessed from RoverBase
+ */
+ RoverCloud myRoverCloud;
+
+ /**
+ * @brief Private RoverDisplay instance that is accessed from RoverBase
+ */
+ RoverDisplay myRoverDisplay;
+
+ /**
+ * @brief Private RoverDriving instance that is accessed from RoverBase
+ */
+ RoverDriving myRoverDriving;
+
+ /**
+ * @brief Private RoverGpio instance that is accessed from RoverBase
+ */
+ RoverGpio myRoverGpio;
+
+ /**
+ * @brief Private RoverSensors instance that is accessed from RoverBase
+ */
+ RoverSensors myRoverSensors;
+
+ /**
+ * @brief Private RoverUtils instance that is accessed from RoverBase
+ */
+ RoverUtils myRoverUtils;
+
+ /**
+ * @brief Flag for indicating whether private RoverGpio object initialized or not.
+ */
+ int ROVER_GPIO_INIT_;
+
+ /**
+ * @brief Flag for indicating whether private RoverSensors object initialized or not.
+ */
+ int ROVER_SENSORS_INIT_;
+
+ /**
+ * @brief Flag for indicating whether private RoverDisplay object initialized or not.
+ */
+ int ROVER_DISPLAY_INIT_;
+
+ /**
+ * @brief Flag for indicating whether private RoverDriving object initialized or not.
+ */
+ int ROVER_DRIVING_INIT_;
+
+
+ public:
+ /**
+ * @brief Constructor for the RoverBase class
+ */
+ RoverBase();
+
+ /**
+ * @brief Destructor for the RoverBase class
+ */
+ virtual ~RoverBase();
+
+ /**
+ * @brief Initializes the RoverBase
+ * @return void
+ */
+ void initialize (void);
+
+ /**
+ * @brief Shuts down the Rover's OS.
+ * @return void
+ */
+ void shutdown (void);
+
+ /**
+ * @brief Sleep function to be used in rover applications
+ * @param Period to sleep in milliseconds
+ * @return void
+ */
+ void sleep (unsigned int period_ms);
+
+ /**
+ * @brief Public function to access private RoverCloud instance.
+ * @return RoverCloud instance
+ */
+ rover::RoverCloud& inRoverCloud (void);
+
+ /**
+ * @brief Public function to access private RoverDisplay instance.
+ * @return RoverDisplay instance
+ */
+ rover::RoverDisplay& inRoverDisplay (void);
+
+ /**
+ * @brief Public function to access private RoverDriving instance.
+ * @return RoverDriving instance
+ */
+ rover::RoverDriving& inRoverDriving (void);
+
+ /**
+ * @brief Public function to access private RoverGpio instance.
+ * @return RoverGpio instance
+ */
+ rover::RoverGpio& inRoverGpio (void);
+
+ /**
+ * @brief Public function to access private RoverSensors instance.
+ * @return RoverSensors instance
+ */
+ rover::RoverSensors& inRoverSensors (void);
+
+ /**
+ * @brief Public function to access private RoverUtils instance.
+ * @return RoverUtils instance
+ */
+ rover::RoverUtils& inRoverUtils (void);
+
+ /**
+ * @brief Initializes private RoverDriving object instance.
+ * @return void
+ */
+ void initializeRoverDriving (void);
+
+ /**
+ * @brief Initializes private RoverGpio object instance.
+ * @return void
+ */
+ void initializeRoverGpio (void);
+
+ /**
+ * @brief Initializes private RoverDisplay object instance.
+ * @return void
+ */
+ void initializeRoverDisplay (void);
+
+ /**
+ * @brief Initializes private RoverSensors object instance.
+ * @return void
+ */
+ void initializeRoverSensors (void);
+ };
+}
+
+
+
+#endif /* ROVER_API_HPP_ */
diff --git a/rover/src/roverapi/rover_api.cpp b/rover/src/roverapi/rover_api.cpp
new file mode 100644
index 0000000..166f65d
--- /dev/null
+++ b/rover/src/roverapi/rover_api.cpp
@@ -0,0 +1,236 @@
+/*
+ * Copyright (c) 2017 FH Dortmund and others
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Description:
+ * Rover API - Interfaces for Rover application development
+ *
+ * Contributors:
+ * M.Ozcelikors <mozcelikors@gmail.com>, created API 17.11.2017
+ *
+ */
+
+#include <roverapi/rover_api.hpp>
+#include <wiringPi.h>
+
+#include <roverapi/rover_cloud.hpp>
+#include <roverapi/rover_utils.hpp>
+#include <roverapi/rover_driving.hpp>
+#include <roverapi/rover_gpio.hpp>
+#include <roverapi/rover_display.hpp>
+#include <roverapi/rover_sensors.hpp>
+
+/**
+ * @brief Constructor for the RoverBase class
+ */
+rover::RoverBase::RoverBase()
+{
+ /* wiringPi can only be called once */
+ wiringPiSetup();
+
+ this->ROVER_DISPLAY_INIT_ = 0;
+ this->ROVER_DRIVING_INIT_ = 0;
+ this->ROVER_GPIO_INIT_ = 0;
+ this->ROVER_SENSORS_INIT_ = 0;
+}
+
+/**
+ * @brief Destructor for the RoverBase class
+ */
+rover::RoverBase::~RoverBase()
+{
+
+}
+
+/**
+ * @brief Initializes the all classes, sensors, libraries for the Rover
+ */
+void rover::RoverBase::initialize(void)
+{
+ this->initializeRoverDisplay();
+ this->initializeRoverDriving();
+ this->initializeRoverGpio();
+ this->initializeRoverSensors();
+}
+
+void rover::RoverBase::shutdown (void)
+{
+ if (this->ROVER_DISPLAY_INIT_ != 1)
+ {
+ fprintf(stderr,"You havent initialized RoverDisplay. Use RoverBase::initialize() !\n");
+ }
+ else
+ {
+ RoverDisplay my_display = this->inRoverDisplay();
+
+ /* Prepare "Shutting Down..." */
+ my_display.clearDisplay();
+
+ my_display.setTextSize(2);
+ my_display.setTextColor(WHITE);
+
+ my_display.setCursor(20,10);
+ my_display.print("Shutting");
+
+ my_display.setTextColor(WHITE);
+
+ my_display.setCursor(20,32);
+ my_display.print("Down...");
+
+ /* Display everything earlier this time*/
+ my_display.display();
+
+ /* Play the shutdown tone..*/
+ this->inRoverGpio().shutdownTone();
+
+ /* Prepare "Shutting Down..." */
+ my_display.clearDisplay();
+
+ my_display.setTextSize(2);
+ my_display.setTextColor(WHITE);
+
+ my_display.setCursor(20,10);
+ my_display.print("Shutting");
+
+ my_display.setTextColor(WHITE);
+
+ my_display.setCursor(20,32);
+ my_display.print("Down...");
+
+ /* Display everything earlier this time*/
+ my_display.display();
+
+ /* Here we're shutting Raspberry Pi down.. */
+ system("halt");
+
+ /* Prepare "Shutting Down..." */
+ my_display.clearDisplay();
+
+ my_display.setTextSize(2);
+ my_display.setTextColor(WHITE);
+
+ my_display.setCursor(20,10);
+ my_display.print("Shutting");
+
+ my_display.setTextColor(WHITE);
+
+ my_display.setCursor(20,32);
+ my_display.print("Down...");
+
+ /* Display everything earlier this time*/
+ my_display.display();
+
+ /* Abort the application for safety reasons */
+ abort();
+ }
+}
+
+void rover::RoverBase::sleep (unsigned int period_ms)
+{
+ if (this->ROVER_DRIVING_INIT_ != 1)
+ {
+ fprintf(stderr,"You havent initialized RoverDriving. Use RoverBase::initialize() !\n");
+ }
+ else
+ {
+ delay (period_ms);
+ }
+}
+
+rover::RoverUtils& rover::RoverBase::inRoverUtils (void)
+{
+ return this->myRoverUtils;
+}
+
+rover::RoverCloud& rover::RoverBase::inRoverCloud (void)
+{
+ return this->myRoverCloud;
+}
+
+rover::RoverDriving& rover::RoverBase::inRoverDriving (void)
+{
+ if (this->ROVER_DRIVING_INIT_ != 1)
+ {
+ fprintf(stderr,"You havent initialized RoverDriving. Use RoverBase::initialize() !\n");
+ }
+ else
+ {
+ return this->myRoverDriving;
+ }
+}
+
+rover::RoverGpio& rover::RoverBase::inRoverGpio (void)
+{
+ if (this->ROVER_GPIO_INIT_ != 1)
+ {
+ fprintf(stderr,"You havent initialized RoverDisplay. Use RoverGpio::initialize() !\n");
+ }
+ else
+ {
+ return this->myRoverGpio;
+ }
+}
+
+rover::RoverDisplay& rover::RoverBase::inRoverDisplay (void)
+{
+ if (this->ROVER_DISPLAY_INIT_ != 1)
+ {
+ fprintf(stderr,"You havent initialized RoverDisplay. Use RoverBase::initialize() !\n");
+ }
+ else
+ {
+ return this->myRoverDisplay;
+ }
+}
+
+rover::RoverSensors& rover::RoverBase::inRoverSensors (void)
+{
+ if (this->ROVER_SENSORS_INIT_ != 1)
+ {
+ fprintf(stderr,"You havent initialized RoverSensors. Use RoverBase::initialize() !\n");
+ }
+ else
+ {
+ return this->myRoverSensors;
+ }
+}
+
+void rover::RoverBase::initializeRoverSensors (void)
+{
+ if (this->ROVER_SENSORS_INIT_ != 1)
+ {
+ this->myRoverSensors.initialize();
+ this->ROVER_SENSORS_INIT_ = 1;
+ }
+}
+
+void rover::RoverBase::initializeRoverGpio (void)
+{
+ if (this->ROVER_GPIO_INIT_ != 1)
+ {
+ this->myRoverGpio.initialize();
+ this->ROVER_GPIO_INIT_ = 1;
+ }
+}
+
+void rover::RoverBase::initializeRoverDisplay (void)
+{
+ if (this->ROVER_DISPLAY_INIT_ != 1)
+ {
+ this->myRoverDisplay.initialize();
+ this->ROVER_DISPLAY_INIT_ = 1;
+ }
+}
+
+void rover::RoverBase::initializeRoverDriving (void)
+{
+ if (this->ROVER_DRIVING_INIT_ != 1)
+ {
+ this->myRoverDriving.initialize();
+ this->ROVER_DRIVING_INIT_ = 1;
+ }
+}
+