Rock7 Core – Endpoints

Following on from the Remote Controlled Weather Station project we’re going to investigate how data gets from your RockBLOCK to your web-server and vice versa. After reading this guide you’ll be fully armed to implement programatic two-way communications to/from your RockBLOCK.

Part 1 – Receiving Messages from your RockBLOCK

Data is sent from your RockBLOCK to one of the 66 earth-orbiting Iridium satellites - it’s brought back down to earth (via a ground station) and is routed to the Rock 7 Core system. It’s at this point that you can control how the data is dispatched, by defining one or more endpoints. (See the Rock 7 Core for RockBLOCK users’ guide for details on specifying these).

Don’t be daunted by the term endpoint, it simply refers to a location where data is sent (e.g. e-mail address or website URL). E-mail endpoints are very useful for debugging, but if you want to do anything more sophisticated, you’ll want to use a URL endpoint where you can in turn process or store the data – this is what we’ll be focusing on in this guide.

Data is sent to your endpoint as an HTTP POST request. For those of you who have dabbled with web-technologies will be familiar with the term; but for those who are new to this, I’ll explain… HTTP is the protocol used ubiquitously across the internet for sending/receiving data between client/server. The protocol defines a number of request methods, one of these is called POST. It’s typically used for submitting form-based data (e.g. when you enter your username and password to log in to a website) and takes the form of a key/value pair structure. So in this example, you’re submitting two parameters: username and password.

This is exactly how the data will sent to your endpoint, however instead of username and password you will receive a data parameter containing the bytes you’ve transmitted. You’ll also receive additional parameters, including a (very) approximate geographic location of your RockBLOCK (accuracy: typically several kilometres). Here is an excerpt from the RockBLOCK developer guide, detailing all the parameters:

Next you’ll need some kind of web hosting solution to host your endpoint to receive the requests. There are countless hosting providers, so i’ll leave it to you to find one that works best for you. Likewise, there are many programming languages available to implement your endpoint. I’ve prepared examples in the most popular web-programming languages: Python, PHP, Java and Perl (it’s not really popular, but i’ve included it because I can). Each example demonstrates how to obtain the parameter values, decode the data parameter and send a suitable response.

import cgi

form = cgi.FieldStorage()

 imei = form["imei"]
momsn = form["momsn"]
transmit_time = form["transmit_time"]
iridium_latitude = form["iridium_latitude"]
iridium_longitude = form["iridium_longitude"]
iridium_cep = form["iridium_cep"]
data = form["data"]

decoded = data.decode("hex")

print "Content-Type:text/html\n\n"
print "OK"

import cgi

form = cgi.FieldStorage()

 imei = form["imei"]

momsn = form["momsn"]

transmit_time = form["transmit_time"]

iridium_latitude = form["iridium_latitude"]

iridium_longitude = form["iridium_longitude"]

iridium_cep = form["iridium_cep"]

data = form["data"]

decoded = data.decode("hex")

print "Content-Type:text/html\n\n"

print "OK"

$imei = $_POST["imei"];
$momsn = $_POST["momsn"];
$transmit_time = $_POST["transmit_time"];
$iridium_latitude = $_POST["iridium_latitude"];
$iridium_longitude = $_POST["iridium_longitude"];
$iridium_cep = $_POST["iridium_cep"];
$data = $_POST["data"];

$decoded = pack('H*', $data);

echo "OK";

$imei = $_POST["imei"];

$momsn = $_POST["momsn"];

$transmit_time = $_POST["transmit_time"];

$iridium_latitude = $_POST["iridium_latitude"];

$iridium_longitude = $_POST["iridium_longitude"];

$iridium_cep = $_POST["iridium_cep"];

$data = $_POST["data"];

$decoded = pack('H*', $data);

echo "OK";

public class RockBlockServlet extends HttpServlet {

	protected void doPost( HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
		
		String imei = request.getParameter("imei");
		String momsn = request.getParameter("momsn");
		String transmit_time = request.getParameter("transmit_time");
		String iridium_latitude = request.getParameter("iridium_latitude");
		String iridium_longitude = request.getParameter("iridium_longitude");
		String iridium_cep = request.getParameter("iridium_cep");
		String data = request.getParameter("data");

		response.getWriter().println("OK");

	}
}

public class RockBlockServlet extends HttpServlet {

protected void doPost( HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {

String imei = request.getParameter("imei");

String momsn = request.getParameter("momsn");

String transmit_time = request.getParameter("transmit_time");

String iridium_latitude = request.getParameter("iridium_latitude");

String iridium_longitude = request.getParameter("iridium_longitude");

String iridium_cep = request.getParameter("iridium_cep");

String data = request.getParameter("data");

response.getWriter().println("OK");

}

#!/usr/bin/perl

use strict;
use CGI qw(param);

my $imei = param("imei");
my $momsn = param("momsn");
my $transmit_time = param("transmit_time");
my $iridium_latitude = param("iridium_latitude");
my $iridium_longitude = param("iridium_longitude");
my $iridium_cep = param("iridium_cep");
my $data = param("data");

print “Content-Type:text/html\n\n”
print “OK”;

#!/usr/bin/perl

use strict;

use CGI qw(param);

my $imei = param("imei");

my $momsn = param("momsn");

my $transmit_time = param("transmit_time");

my $iridium_latitude = param("iridium_latitude");

my $iridium_longitude = param("iridium_longitude");

my $iridium_cep = param("iridium_cep");

my $data = param("data");

print “Content-Type:text/html\n\n”

print “OK”;

What is hex-encoding?
Data sent from the RockBLOCK will be passed to your endpoint as a hex-encoded string. If you were to send the string MS - it would be converted into its hexadecimal value (ASCII / Latin-1 encoded) as 0x4D53, this will be sent to your endpoint stringwise as “4D53“. Likewise, if you were to send the string Makersnake, the string “4d616b6572736e616b65” would be received. The website string-functions.com provides handy tools for converting to/from hex-encoded strings.

Important
It’s essential that you respond quickly (within a couple of seconds) to requests; if you don’t the delivery is considered to have failed. This will result in further delivery attempts until a successful response is received. An acknowledging response is considered to be anything that has a HTTP 200 status code, so simply outputting OK will be sufficient.

I found this out the hard way: Whilst developing my remote controlled weather station project, I was sending an e-mail each time a request was received; which worked fine most of the time, except when my mail server responded slowly. This had the knock on effect that my acknowledging response was not sent for several seconds. As a consequence, the delivery was considered a failure and the same message was subsequently redelivered several times! (Thanks to splendid Rock 7 Support for helping me with this!)

Part 2 – Sending messages to your RockBLOCK

As you’ll recall from the Remote Controlled Weather Station project, we implemented a mechanism to remotely update the transmission frequency; by sending F:XXX the update frequency will be changed to XXX seconds. Sending messages works the same way, except you send the HTTP POST request to the Core (instead of receiving requests from the Core).

HTTP POST requests are sent to: https://core.rock7.com/rockblock/MT with the following parameters:

imei – your unique identifier for your RockBLOCK (15 digits long, starting 30023)
username/password – your Rock 7 Core login credentials
data – the hex-encoded message (e.g. Hello = 48656c6c6f)

If the request has been successful, you’ll get a response like this: OK, XXXXXXXX (Whereby, XXXXXXXX is a unique identifier for your message)

If there is a problem, for example message is too long, or you’ve got insufficient credits then the web-service will response as below:

FAILED, XX, YYYYYY (Whereby, XX is the error code and YYYYYY is a human readable explanation of the error).

A full listing of the response codes can be found in the official RockBLOCK documentation.

Here are some examples of how you’d programatically send the message “F:100″ (463a313030) to your RockBLOCK.

Python

import urllib
import urllib2

url = 'https://core.rock7.com/rockblock/MT'
values = {'imei':'300230000000000', 'username':'makersnake', 'password':'secret', 'data':'463a313030'}

data = urllib.urlencode(values)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
responseString = response.read()

import urllib

import urllib2

url = 'https://core.rock7.com/rockblock/MT'

values = {'imei':'300230000000000', 'username':'makersnake', 'password':'secret', 'data':'463a313030'}

data = urllib.urlencode(values)

req = urllib2.Request(url, data)

response = urllib2.urlopen(req)

responseString = response.read()

PHP

request = new HttpRequest("https://core.rock7.com/rockblock/MT", HttpRequest::METH_POST);

$request->addPostFields(array('imei'=>'300230000000000', 'username'=>'makersnake', 'password'=>'secret', 'data'=>'463a313030'));

$response = $request->send()

$responseString = response->getBody();

request = new HttpRequest("https://core.rock7.com/rockblock/MT", HttpRequest::METH_POST);

$request->addPostFields(array('imei'=>'300230000000000', 'username'=>'makersnake', 'password'=>'secret', 'data'=>'463a313030'));

$response = $request->send()

$responseString = response->getBody();

Java

HttpClient agent = HttpClients.createDefault();
HttpPost request = new HttpPost("https://core.rock7.com/rockblock/MT");

List params = new ArrayList(4);

params.add(new BasicNameValuePair("imei", "300230000000000"));
params.add(new BasicNameValuePair("username", "makersnake"));
params.add(new BasicNameValuePair("password", "secret"));
params.add(new BasicNameValuePair("data", "463a313030"));

request.setEntity(new UrlEncodedFormEntity(params, "UTF-8"));

HttpResponse response = agent.execute(request);

HttpEntity entity = response.getEntity();

HttpClient agent = HttpClients.createDefault();

HttpPost request = new HttpPost("https://core.rock7.com/rockblock/MT");

List params = new ArrayList(4);

params.add(new BasicNameValuePair("imei", "300230000000000"));

params.add(new BasicNameValuePair("username", "makersnake"));

params.add(new BasicNameValuePair("password", "secret"));

params.add(new BasicNameValuePair("data", "463a313030"));

request.setEntity(new UrlEncodedFormEntity(params, "UTF-8"));

HttpResponse response = agent.execute(request);

HttpEntity entity = response.getEntity();

Perl

#!/usr/bin/perl

use LWP::UserAgent;

my $agent = LWP::UserAgent->new;

my $req = HTTP::Request->;new(POST=>; "https://core.rock7.com/rockblock/MT");

my $values = {'imei':'300230000000000', 'username':'makersnake', 'password':'secret', 'data':'463a313030'};

$req->content($values);

my $response = $agent->request($req);

my $responseString = $response->decoded_content;

#!/usr/bin/perl

use LWP::UserAgent;

my $agent = LWP::UserAgent->new;

my $req = HTTP::Request->;new(POST=>; "https://core.rock7.com/rockblock/MT");

my $values = {'imei':'300230000000000', 'username':'makersnake', 'password':'secret', 'data':'463a313030'};

$req->content($values);

my $response = $agent->request($req);

my $responseString = $response->decoded_content;