Makersnake

Makersnake

Software writing, 3D printing, hardware hacking and all-round geekery

jsaw

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:

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.

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

PHP

Java

Perl

 

9 Comments

  1. Paul McWhorter

    Thank you for the code to allow receiving data from rockblock. Could you say just a few words of how to implement this code. Do you save the code as the index.html page of the WEB site, or how do you name the file, and where do you put it on the WEB site? Any additional help would be appreciated.
    PJM

  2. Makersnake

    Hey Paul,

    It all depends on what your web-hosting provides and how it’s setup – so it’s hard to provide definitive answers!

    Take a look at some basic examples to get up to speed with a hello world example; i’d recommend Python.

    Here’s a link that should put you in the right direction: https://docs.python.org/2/howto/webservers.html

  3. Paul McWhorter

    Thank you for the guidance. I am finding that my godaddy hosting is not wanting to run python or pearl scripts, but does appear to be OK with PHP.

    I really appreciate your help as my expertise is arduino/raspberry pi/python/circuits, and the WEB stuff is not easy for me. Would the following work.

    1) I create a file in my WEB root directory called rb.php
    2) I use the script you provide above
    3) I point the Rockblock to http://www.mydomain.com/rb.php
    4) I send a test message from rockblock, which is then directed to 3) above

    If I do this, then where does the data end up from your script? Is there a text file in my root folder your script directs the data to, or where do I now find the data.

    I really appreciate your help. I have spend about 20 hours trying to figure this out, but there are no simple tutorials to follow on how this works, so if you could give me some guidiance I would greatly appreciate it.
    Thanks!
    PJM

  4. Makersnake

    It’s easy when you know how, yes the above will work in principle…

    At the moment, the example php does nothing with the data (it’s not saved anywhere) – so you’ll need to add this code to the script.

    Here’s a tutorial to get you going: https://www.w3schools.com/php/php_file_create.asp

    You should just be able to append the variables into the file, something like:

    $myfile = fopen(“rockblock-data.txt”, “a”) or die(“Unable to open file!”);
    fwrite($myfile, $transmit_time);
    fwrite($myfile, ” “);
    fwrite($myfile, $data);
    fwrite($myfile, “\n”);
    fclose($myfile);

    If you have any problems opening the file – it’ll probably be an issue with file permissions.

    Good Luck!!

  5. Paul McWhorter

    Got it! I had not done PHP before, so did not understand the code. Went through a few PHP examples, and now have it all working.

    The biggest problem that I had with this is that at the end of the day it appears that Godaddy does not allow Python or Pearl scripts. PHP is allowed, so this was the solution.

    I really appreciate the help on this.
    Thanks!

  6. Makersnake

    Great – glad you got this working Paul!

    If you do something cool with your RockBLOCK do let us know!

  7. Paul McWhorter

    Wlll do . . . we are putting together a system we will put the edge of space on HAB. We are hoping to exceed 135,000 feet in altitude. Launch will is planned for mid may.

  8. Chad Taylor

    In a current project of mine using Twilio to send and receive text messages back and forth between my server and getting responses based on command I am somewhat familiar with the idea of using the POST back and forth. However Twilio provides a mechanism that protects the script on my server by with apache auth like this below…

    http://username:Password@myserver.com/sms-control/receive.php

    Can the RockBlock system do the same?

  9. Makersnake

    Chad – Yep I think so, you should be able to define your endpoint in the RockBLOCK admin system per your example URL (e.g. providing your username/password).

    What we do is only accept requests from certain IP addresses (the ones used for posting the data from Rock7) – this protects us from any nefarious posts.

Leave a Comment

Your email address will not be published. Required fields are marked *