Native Command Overview
Nebula is supplied with all the commands that it needs, plus a range of working example commands to assist developers in getting their projects running quickly. Native commands are those required to install and manage devices and the VPN. Not all commands are shown to the user. Some commands are only used for background VPN operations or in support of other commands. Whether to show a command to the user or not is one element in the Nebula Command class that is defined when the command is created. Ping and DeleteFromVpn(Remove) are user visible commands. The other commands for VPN management are used in the background for installation and device management. Native commands are implemented on all APK, JAR devices.
BIN devices implement all except SMS commands, DeleteFromVpn and SetHubXferMode. BIN devices can be removed from the VPN by APK or JAR devices but they cannot cause other devices to be removed from the VPN. SetHubXferMode is a special command used for SendFile and GetFile streaming data. BIN devices do not have file transfer streams implemented due to their limited memory. Note that Nebula code for BIN devices, while written in Arduino.ino format, is primarily intended for WiFi and WiFi/BT modules. There is no technical reason for not implementing these commands, it was just deemed unnecessary for Nebula demonstration.
The client makes a CSV of the device to remove and sends it with this command to Device 1. Device 1 sends DeleteDevice with the CSV of the device to remove to all known devices. The device being removed will recognize itself, delete its Nebula database files and close the Nebula app. On restart of Nebula, the removed device will enter its Installation mode as a new device to be added to the VPN.
- mode 1 = both devices are home
- mode 2 = client device is away, server device is home
- mode 3 = client device is home, server device is away
- mode 4 = both devices are away
Client device is sending, server device is receiving. Away means a device is mobile or connected to a LAN that is not the home LAN. Home LAN is the one Device 1 is on. When a device is away, it uses the public address of the home LAN to reach devices at home via the hub. A second consideration is if Device 1 is the one sending or receiving the data stream. Nebula determines the mode and sends this command to Device 1 if the mode is 2,3 or 4 and Device 1 is not the sender or receiver of the stream. For mode 1 or Device 1 being the sender or receiver, streaming is direct device to device.
This command is sent only to Device 1. It causes the hub device to set itself up as a central server for streaming data. When Device 1 receives this command it sets up two socket servers using the 2 stream ports that are forwarded to it. It then starts a connect thread to wait for the receiving and sending devices to connect. After both receiver and sender connect, it starts a stream thread that reads incoming data bytes from the sender and passes them to the receiver.
While this command is only used for Nebula file transfer examples, it is a native command because it provides the fundamental ability to setup the hub, or any APK or JAR device that can be reached on a public network, as a central server. Having central server ability is important especially for mode 4 conditions where an SMS conversation between devices is impractical.
If the VPN public address is not a DNS reference, then Device 1 will check if the public address has changed during Startup. If it has changed it will send this command to all known devices when it enters Running. Any device that is offline or in any way fails to receive and successfully execute this command will not be able to contact Device 1. It will effectively be lost to the VPN.
There are 6 native commands implemented in Nebula for sending and replying to commands via SMS text messages. Following is a brief description of each. SMS command details are covered here.
When a mobile device receives a command via SMS text, it runs the received command then responds by sending this command with any response in the payload. When the client receives this command, it will process the response to SMS command it sent, then reply with “OK” which closes the HTTP connection with the mobile device.
If the sending device has a static address it is assumed to be an AWS device, which may not always be true but Nebula code is for demo purposes. So with this command the AWS device will send the command to Device 1 and Device 1 will send the SMS. This command changes the from device ID of the SMS to the AWS device so after the command has been run the mobile device will send, via HTTP, an SmsCmdReply with the response to the AWS device.
Example Commands Overview
Nebula comes with commands to assist developers in getting their projects running quickly. The example commands provide usable code to do a variety of common network operations. They illustrate not only how to implement commands but also how commands can be used to launch support activities for user input , background threads, database operations, data streaming - both device to device and streaming using the hub(Device 1) as a central server and more.
Nebula file transfer is intended as foundational code for apps like file, photo, video and music sharing. For simple messaging apps a single command can transfer the text in its payload.
File transfer operations are implemented on JAR and APK devices. BIN devices implement a SPIFFS (Serial Peripheral Interface Flash File System). It’s a light-weight file system for micro-controllers that may only have an SPI flash chip for memory. BIN devices have file read/write methods included but they are only used to maintain the Nebula database files at this point. It’s up to a developer to implement any file operations on BIN devices to support their application.
During device installation on JAR devices Nebula creates R/W directories Documents, Photos, Download, Music and Movies in the $HOME/Nebula directory. On APK devices the same directory names (Photos are DCIM/Camera) are verified as R/W at /storage/emulated/0/ , which are the current standard file directories of Android devices. Files must be located in one of these directories and will be transferred to/from the same directory on the server. After device installation the directories are empty on JAR and may be empty on APK. You will have to save files to them to see results. Nebula will show the files it finds in a selected directory except sub-directories and hidden files(those beginning with “dot”).
SendFile, GetFile and DeleteFile are the user selectable commands. A FileSelectActivity class provides a user interface for selecting the directory/file to transfer. GetFileList is a background support command used for retrieving a list of files locally or on a remote device. CheckFile is a background command for verification of the file after it’s been transferred. Classes FileStreamClient, FileStreamServer and if required, native command SetHubXferMode are used to setup the threads that actually transfer the file data.
Delete file occurs immediately without confirmation on command execution, so be careful. The differences between SendFile and GetFile is determined at run time by the transfer mode and how the classes FileStreamServer and FileStreamClient interpret the mode. Both classes are capable of read-socket-write-file or read-file-write-socket. Both also provide a callback interface to inform when all file bytes have been read or written or a failure occurred.
The following image is the FileSelectActivity screen which opens when a file operation is requested. It consists of a User Information block, a button(JAR) or swipe-right(APK) to clear the user info, a drop-down directory selector, a block to show and select from the available files in the selected directory, an EXIT button to end file operations and an EXECUTE button to initiate a file operation.
USAGE: 1. Drop-down and select a directory 2. Click Show Files 3. Select a file 4. Click EXECUTE 5. Repeat 1-4 as necessary for same command 6. Click EXIT or Back button when finished
Send, Get and Delete File
Database operations form the basis of many applications where sensors are used to monitor equipment or some environment. To evaluate database commands you should start by sending several DatabaseWrite commands to a selected device. Each time the command is received the selected device will write one row of data to the database on Device 1. After several DatabaseWrites, select DatabaseRead and send it to the same device that was writing. The response will be a line graph showing the date/time and data sent to the database. The Nebula Database commands serve only as examples. They essentially “speak” MySQL to each other and illustrate how commands may be nested, redirected and the footer code used to modify how the command behaves.
The importance here is that with the purchased version of Nebula a developer will be able to:
- The example database is simple:
- MySql user name: nebula
- MySql password: nebula
- Database name: “DeviceSensorData” It has one table.
- Table name: “sensorData” It has three columns.
|date time||device name||data value|
Streaming video is accomplished by using one of the dedicated stream ports. Nebula provides examples of use by streaming MJPEG video from either the front or back camera of an Android device to an APK or JAR client. The stream command starts with the client sending a request for the selected camera. The server verifies it has the requested camera then starts the stream on its stream port. It responds with a CSV of camera ID, port number, camera rotation and frames/second. The client uses this response to connect to the stream and display the video in a separate window that also has a STOP button. The video stream commands illustrate how to stream data when one or both devices are home using only one of the forwarded stream ports. If you want to stream video between two mobile devices, the developer would have to implement the logic used for streaming files where the hub is used as a central server.
IMPORTANT In order to limit data usage the Nebula examples stream video at 320x240 resolution and 15 frames per second. Be careful with these commands if you are mobile and do not have an unlimited data plan. You will be using 30-60KB of data per frame depending on the video scene.
HTML web-pages are a common way to control devices over the Internet. Nebula demonstrates web-page control by embedding simple HTML code in devices. You can see an example in ServerHandler.webresponse(). It allows control from APK and JAR devices using a simple BrowserActivity class. Web-pages are controlled using HTTP request methods(GET, POST, PUT etc.). For security Nebula only recognizes commands that are sent with POST. GET requests are specifically enabled for web-page control and disabled with the WebStop command. The web-page for APK and JAR devices provide a button to start/stop some “work”. The server’s Running text box will show the action of the client’s button clicks. For BIN devices the modules log output has to be watched for LED-color and relay ON/OFF messages.
Nebula provides examples of speech-to-text using Android’s RecognizerIntent and text-to-speech using Android’s Speech class. Voice control is also implemented in BIN devices to give an example of how to implement key-words in a Nebula command.
Android devices usually contain a range of built-in sensors. Temperature, device position, compass, accelerometer and GPS among them. Nebula lists all the sensors and their type in the device start-up log. Nebula can access the data generated by any sensor, process it and send it, via command, to another Nebula device. Sensor data can be operated on directly or sent to a database for later retrieval.