Built-in Commands

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.

Native Commands

Ping

User command - Implemented on all devices.
This is the fundamental “are you listening?” command. It is not using the standard network Ping protocol, but a command using Nebula protocol. The success response from the server is a string that states “<server device name> has been pinged”. A failed response occurs if the device the command was sent to is either off-line, cannot be reached or the Nebula app is not running.

GetDatabase

Background command - Implemented on all devices.
Typically sent to Device 1 during installation to retrieve the network and device database. Response is the network and device database from the server the command was sent to. Probably a good idea to limit this command to Device 1 with both devices connected on the private home network.

SyncDatabase

Background command - Implemented on all devices.
Sent to Device 1 on Nebula startup to verify that device databases are in sync. A hash of the client device database is sent with the command. Device 1 compares the received hash with a hash of its device database. If the hashes match “DBOK” is returned. If the hashes do not match, the response is the device database from Device 1.

AddDevice

Background command - Implemented on all devices.
Send to any device. Include a Comma Separated Values(CSV) string payload describing the device to add. Nebula includes utility methods for conversion of a Device object to CSV and CSV to Device.

ModifyDevice

Background command - Implemented on all devices.
When a device detects a change, like going mobile or connecting to a different hot-spot access point it will update itself first then send this command to Device 1 with a CSV of itself containing the changes. Device 1 will send this command to all other known devices with the CSV of the changed device. Devices receiving this command will update their device database with the changes.

DeleteDevice

Background command - Implemented on all devices.
Send to any device. Include a payload with the device CSV to delete. Devices receiving this command will remove the device identified in the payload from their device database.

DeleteFromVpn

User command - Implemented on APK and JAR devices.
Shown to user as Remove and typically only used during development and debug. The device selected with this command will be removed from the VPN. Device 1 cannot be removed using this command. BIN devices can be removed with this command but not send it.

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.

SetHubXferMode

Background command - Implemented on APK and JAR devices.
When sending a streaming command 4 modes must be considered:
  • 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.

NewPublicIp

Background command - Implemented on all devices.
If your router experiences a power failure or hard reset your Internet Service Provider (ISP) may issue a new and different public IP address. For a VPN this can be catastrophic. Device 1 and thus all home devices become unreachable from outside devices. Having a DNS reference to your public IP address solves this issue and is highly recommended for long term stability of your VPN.

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.

SMS Commands

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.

SmsCmdReply

Background command - Implemented on APK and JAR devices.
Nebula provides code to send an SMS text to a mobile device. It uses the feature to send commands using a specially coded text which causes the command to run on the mobile device. SMS is necessary because the IP address assigned by the service provider allows the mobile device to act as a client only not as a server. Mobile devices send requests, or Nebula commands, and receive a reply over HTTP.

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.

SmsEndReply

Background command - Implemented on APK devices only. Nebula assumes that JAR devices do not go mobile.
This command is used for mode 4. That is both the command sender and receiver are mobile. The commands and responses are via SMS. Nebula determines if an incoming SMS is a command to be run or a reply to a command that has been run. If the SMS is a command to run, Nebula will return the result of the command’s parserRunCommand() method wrapped in a SmsCmdReply as explained above. If the SMS is a reply to a command that has been run, it means both devices are mobile and Nebula will return the result of the command’s clientPostAction() method wrapped in SmsEndReply. Without this command, mobile to mobile communication would cause an endless loop with both devices relpying to SmsCmdReply.

SmsPutOn1

Background command - Implemented on APK and JAR devices.
This command is sent only to Device 1 with a payload that represents an SMS command that is greater than 140 bytes. Device 1 will save the payload at StaticValues.bigSms for retrieval by the mobile device.

SmsGetOn1

Background command - Implemented on APK and JAR devices.
This command is only sent via SMS to a mobile device. It informs the mobile device to retrieve a command from Device 1 that was greater than 140 bytes. No payload is sent with this command insuring that it will be less than 140 bytes even if encrypted.

SmsGetFrom1

Background command - Implemented on APK and JAR devices.
This command is only sent to Device 1 from a mobile APK device. Device 1 will reply with the string contents of StaticValues.bigSms which is any command that was greater than 140 bytes that could not be sent via SMS due to its size.

SmsSendForAWS

Background command - Implemented on JAR devices. Nebula assumes that a cloud server is a JAR device.
Amazon Web Server(AWS) cloud devices will not send an email, for SMS, without signing up for their Amazon Simple Email Service (SES) service. This command is a work-around where SendCommand.smsOP() tests if the sending device has a static address.

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.

File Transfer

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.

../_images/fileSelector.png
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

User commands - Implemented on JAR and APK devices.
Select the command and the device to send the command to. Then click the send button. The File Chooser will open and show the selected command and the device the command will be sent to. Then follow the USAGE sequence listed above.

GetFileList

Background command - Implemented on JAR and APK devices.
Sent to a device with a payload containing the selected directory name. The local(for SendFile) or receiving(for GetFile) device responds with a CSV list of the file names and their size contained in the selected directory. The files are then shown to the user for selection.

CheckFile

Background command - Implemented on JAR and APK devices.
At the end of a file transfer the sending device will send this command with a checksum(SHA-256) of the file sent. The receiving device will verify that the file received matches. A match returns the commands success code or a failure returns this command’s ID.

Database Control

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:

1. Design and establish a MySQL database from code.
2. Write data to the database using a command.
3. Read data from the database using a command.
4. Graphically present data to a user.
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

DatabaseRead

User command - Implemented on APK and JAR devices.
Requires that a database is setup on Device 1. The command demonstrates how a command may be redirected to a different device. The name of the selected device is sent to Device 1. Device 1 runs a SELECT * FROM <selected device> and returns all from the data column of <selected device>. The returned data is plotted as a line chart on the sending client.

DatabaseWrite

User command - Implemented on all devices.
Requires that a database is setup on Device 1. The command demonstrates how commands may be nested. The device that receives the command sends a row consisting of the current date and time, its device name and a random data value to Device 1 for storage in its database. The nesting occurs because the receiving device runs a different command in response to the one it received. It returns the nested(MySQL) command’s success/fail reply to the sending client.

DBwriteReply

Background command - Implemented on all devices.
Sent only by BIN devices to others. BIN devices cannot nest commands. So when a BIN device receives a DatabaseWrite command it sets a flag then replies with “Please wait a moment”. When the BIN device gets back to the loop() method, it sees the flag set and sends a DBwrite command with a random number to Device 1. It also puts a code in the footer which tells Device 1 to add date/time and the sending device name to the database entry. The BIN device then uses this command to send the success/fail reply from Device 1 back to the original client.

DBwrite

Background command - Implemented on all devices.
Used to actually send a row of data to a device that has a database, that being Device 1 for demonstration purposes. This is the “nested” command used by DatabaseWrite and DBwriteReply described above.

Video Stream

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.

VideoCameraFront

User command - Client and server implemented on APK devices. Client only implemented on JAR devices.
Displays an MJPEG compressed video stream from the front camera of an Android device.

VideoCameraBack

User command - Client and server implemented on APK devices. Client only implemented on JAR devices.
Displays an MJPEG compressed video stream from the back camera of an Android device.

VideoStopStream

User command - Implemented on APK and JAR devices.
A button on the video display window which when clicked will send the command to the server, stopping the video stream. Also demonstrates the use of sending commands while the stream port is in use.

WebPage Control

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.

WebControl

User command - Send/Receive on APK and JAR, receive only on BIN devices.
The client sends this command with a URL (address:port) contained in its payload. The device receiving the command (host) enables GET requests and responds with success. At the same time, the host starts serving the web-page and waits to receive incoming GET requests from the clients browser. When the client receives the hosts success response, it opens a browser to the requested page. The client then has control using the text and widgets provided by the host’s web-page. NOTE: A mobile device cannot host a web-page as its IP address is restricted, devices while mobile can only act as a client and control home devices via their associated web-page.

WebStop

Background command - Send/Receive on APK and JAR, receive only on BIN devices.
The default browser opens in a separate window. Also on the screen is a EXIT button which when clicked will send this command to the device hosting the web-page. The host will disable GET requests, stop hosting the page and respond success. When the client receives the response it will close the browser window and return to the Running screen.

Voice Operations

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.

VoiceControl

User command - Send/Receive on APK, receive only on JAR and BIN devices.
Keywords for JAR and APK devices are “hello” and “time”. JAR devices will display text responses while APK devices will use text-to-speech and “say” their response using the device’s default voice. BIN devices require two keywords, one for element and one for control. Keywords for BIN device elements are “red”, “yellow” and “all”, or Relay with keywords “relay” or “power”. Control keywords are “on”, “off” or “blink”. Relay is “on” or “off” only it cannot “blink” and is not included in “all”. You can say anything as long as the keywords are present. Say “What time is it” for APK or JAR or “Turn the power on” for BIN.
On issuing this command the client will open the speech-to-text utility. The user will say a command which contains pre-programmed key-words. The client will receive the speech converted text and filter out the key-words which will then be used in the payload of this command and sent to the receiving device. The receiver will parse the key-words, perform the requested action and respond with a success or failed command response.

VoiceRepeat

User command - Send/Receive on APK, receive only on JAR devices.
On issuing this command the APK client will open the speech-to-text utility. The user can say anything and it will be converted to text. The text is sent as the payload with the command to the selected device. The receiving device will convert the payload text and the speech will be heard in the default voice set on the receiving device and respond with a success or failed command response. The command is enabled on JAR devices for developers to implement their own audio in/out and speech-to-text functions. If sent by a JAR device to an APK device, the APK device will “say” an error message in its default voice.

Device Location

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.

WhereIs

User command - Send/Receive on APK, send only to APK for JAR devices.
This command uses the GPS sensor and a Google search to locate a device. A device sends this command to another device with no payload. The receiving device returns its last known latitude and longitude in the response payload. The sending device uses “Map latitude,longitude” as the search term for a web search. The sending device will open its default browser to a page which usually has a map with a pin at the receiving device’s location. The user can open any of the search responses and click the BACK button of the device to return to the Nebula Running screen.