Gadgeteer Library Documentation

 
It is important for any system to be properly documented about the important components and description of libraries and API that the system exposes. Since our project is mainly focused on creating APIs and libraries, it is highly imperative that all the functionalities are properly documented so that others can use them based on their needs.


Gadgeteer Library
This section briefly describes the process of using Gadgeteer library, along with the description of major classes, from which developers can understand how to use the library to manage sensors, log both real time and hostoric data by communicating with the web services. Classes which aim to improve the security and reduce complexity in the development of hardware-based applications are also explained


Class Diagram
Figure 1 shows all the classes contained in the library, as well as their relationships. (see Attachment 1)


How to Use the Library
To use the library, several steps are involved:
1. First the developer has to construct an instance of the class RESTClient by passing an object of the class Device and an ArrayList of Sensor’s objects.
2. Secondly the developer needs to register the sensors that can generate data which can be completed by invoking the method Register of class RESTClient. Note that the sensors should be under the same device.
3. If the return value of the method Register is true which means the registration has been completed and the web service is ready to receive data from the sensors, the developer can either invoke the method SendCurrentData to send real time data or the method SendHistoricData to send data that had been store locally.
4. Since the data should be timestamped, in the static class NtpClient developers can either get the current UTC time from an NTP server by calling GetNetworkTime or initiate a time service supported by Gadgeteer by calling TimeServiceSetting.
5. If the return value of the SendCurrentData or SendHistoricData is true, it indicates that data logging is successful.
6. Throughout the process, the developer needs to constantly invoked the method HeartBeatMessage to send messages to the web service to show the sensors are working.
7. Once the IP Address of the device has been changed, the developer should call the method NotifyIPAddress to send notifications to the web service.
8. Once there is a missing device discovered, for the developer to notify the web service about the information of that device, a method NotifyMissingDevice has to be called.
9. Instead of manually configuring, by invoking a static method ReadConfiguration of the class ConfigurationManager, a configuration file in XML format, able to be downloaded from the web site, can be parsed to configure the necessary information for the device.
10. Additionally, developers can make use of the class HttpUtility to encode and decode URL to and from the format which can be tramitted over the Internet, as well as converting the MAC Address from a byte array to a string.
11 Furthermore, to improve security developers can perform Secure Hash Algorithms on the transmitting data such as registration information and sensor-derived data by means of the two methods, computeHMACSHA256 and computeHMACSHA256, in the class SHA.

Major Classes

RESTClient

Figure 2 REST Client Class Diagram (see Attachment 2)
Description:
Handles the communication with REST-ful web services.
Porperties:
Device: Every instance of the class RESTClient is associated with a Device object which contains necessary information such as device ID.
Sensors: Every instance of the class RESTClient is associated with a list of Sensor objects under the same device which contain necessary information such as sensor ID.
Methods:
Method Summary Parameters Return Value
AppendFile Appends the data gathered from the sensors to the specified file String filePath: Path of the specified file which stores the data
ArrayList sensorData: An ArrayList of TimedData objects contains data gathered from the sensor to be appended
DeleteFile Deletes the specified file String filePath: Path of the file to be deleted
DeleteSensor Deletes the sensor from web service String sensorName: Name of the existing and registered sensor Returns true if the deletion is successful, or false if failed
HeartBeatMessage Sends heart-beat messages to the web service to announce that the device is still working Returns true if the notification is successful, or false if failed
NotifyIPAddress Sends a notification to the web service if the IP Address of a certain device is changed String ipAddress: New IP Address of the device Returns true if the notification is successful, or false if failed
NotifyMissingDevice Sends a notification to the web service if a device is missing Stirng deviceID: ID of the missing device
String userID: ID of the user of the missing device
String sensorID: ID of the sensor of the missing device Returns true if the notification is successful, or false if failed
RegisterSensor Registers the sensors associated with the RESTClient instance Returns true if registration is successful, or false if failed
RESTClient (constructor) initialises the instance String apiKey: Unique API Key got from adding a device on the web site
Device device: Device information
ArrayList sensors: An ArrayList of sensors which contain necessary information under the same device
SendCurrentData Sends the live data gathered from the sensors to the web service ArrayList sensorData: An Arraylist of the TimedData objects which contain live data gathered from the sensors
String firstTime: Timestamp of the first entry of the live data
String lastTime: Timestamp of the last entry of the live data
String sensorName: Name of the sensor which generates real time data Returns true if data sending is successful, or false if failed
SendHistoricData Sends the historic data which is stored in a specified file to the web service String filePath: Path of the file which stores the historic data
String firstTime: Timestamp of the first entry in the file
String lastTime: Timestamp of the last entry in the file
String sensorName: Name of the sensor which generates real time data Returns true if data sending is successful, or false if failed

HttpUtility

Figure 3 HTTP Utility Class Diagram (see Attachement 3)
Description:
Provides functionalities which have been extensively used when programming in the context of HTTP
Methods:
Method Summary Parameters Return Value
GetMACAddress Converts the MAC Address from a byte array to a string byte[] PhysicalAddress: The MAC Address in byte array Returns the MAC Address in string
UrlEncode Converts characters into a format that can be transmitted over the Internet string str: String to be encoded Returns an encoded string with unsafe ASCII characters replaced with a "%" followed by two hexadecimal digits
UrlDecode Converts characters that can be transmitted over the Internet in to a common string string url: Url to be decoded Returns a decoded string from the given one with %## encoding
HexToInt Converts a character from the hexadecimal format to an decimal integer char h: The hexadecimal character to be converted Returns an decimal integer

NtpClient

Figure 4 NtpClient Class Diagram (see Attachement 4)
Description:
Static class to receive the time from a NTP server.
Methods:
Method Summary Parameters Return Value
GetNetworkTime Gets the current DateTime from time-a.nist.gov A DateTime containing the current time
GetNetworkTime Gets the current DateTime from the server specified by the parameter string ntpServer: The hostname of the NTP server A DateTime containing the current time
GetNetworkTime Gets the current DateTime from the server specified by the parameter IPEndPoint ep: The IPEndPoint to connect to
TimeServiceSetting Configures the time service to be able to retrieve the current time from the speicified server Returns a pre-configured instance of the class TimeServiceSettings

ConfigurationManager

Figure 5 Configuration Manager Class Diagram (see Attachement 5)
Description:
Manage the configuration file downloaded from the web site on device mangament page.
Methods:
Method Summary Parameters Return Value
ReadConfiguration Reads the configuration file of the device which can be downloaded from the web site FileStream xmlStream: Instance of the FileStream of the configuration file Returns an instance of the AppSettings class. It constains device’s information needed for sensor registration

SHA

Figure 6 SHA Class Diagram (see Attachement 6)
Description:
Static class providing Secure Hashing Algorithm (SHA-1, SHA-224, SHA-256).
Methods:
Method Summary Parameters Return Value
computeHMAC_SHA256 Compute HMAC SHA-256 byte[] secret: Secret
byte[] value: password 32 byte HMAC_SHA256
computeSHA256 Compute SHA-256 digest byte[] input: Input array 32 byte SHA256

 

Attachments can be found (under Page Info)

Last edited Sep 12, 2013 at 11:42 AM by comarios, version 6