A detailed tutorial on how to program the GPS rover and base to be compatible for use with the Freewave Z9-T TTL radios.
A detailed tutorial on how to program the GPS rover and base to be compatible for use with the Freewave Z9-T TTL radios.
Now that we can send and receive data using the Freewave radios on passthru mode, it’s time to use them to send RTK data and get and RTK fix with a GPS. If you’re using this post as a guide for connecting the radios and haven’t yet sent data via the radio link, go back to the first configuration of the Z9-T DEVKIT blog post and follow the setup procedure listed there.
Rover: The rover is the GPS unit used to read actual position measurements. It receives corrections from a “Base” GPS unit to resolve a very specific geo-spatial reading.
Base: The base is the GPS unit that has a stationary position and sends RTK corrections to the “rover.”
Gateway: This is the server radio in a network. Its serial RXD connects to the Base’s serial TX. There can only be one gateway in a network and any data received by the gateway’s serial RX transmitted to all the endpoints in the network.
Endpoint: This is the radio that receives all data transmitted by the gateway. With our application the endpoint’s are connected to the rovers in the network. The endpoint’s TXD connects to the GPS RX2.
The Navspark S2525F8-GL-RTK is an RTK GPS module that is able to use corrections sent from another receiver to cerrect it’s readings and improve GPS spatial resolution from 3-5m to 1cm. Two GPS units are set up as “rover” and “base.” The base sends correction data to the rover on a UART serial connection, the rover then uses these corrections and outputs location strings in NMEA format on a separate UART.
Here are the settings for RTK communication:
After the radios have been configured, disconnect them from their power sources. On the gateway, move the 5 pin x 2 pin jumper block to the D9 TTL port setting. The D9 TTL connector is used for communication with the GPS unit. To connect the D9 port to the Navspark base, use female stacking row headers (a row of 4 and a row of 5) inserted into the D9 port and jumper cables connected to the Navspark’s RX1 and GND pins. The GPS GND connects to the Freewave GND (D9 TTL port, pin 5) and the GPS TX1 connects to the Freewave RXD (D9 TTL port, pin 3).
To verify that data is being read, sent, and received with the Freewave radios, power on the endpoint and connect it to an opened terminal. Check that the endpoint is communicating with the terminal by opening the Freewave shell. Check that system.serialmode=Passthru_Data, then save and exit the Freewave shell but leave the terminal open. Now that you’ve updated the settings for the radios’ serial protocol, check the Tera Term serial port settings and make sure that they are matching the settings the freewave SerialPortConfig showed. Specifically the baud rate is 115200 and flow control is off. Once you see the terminal filling with random characters coming in once every second with the settings as shown, the Freewave radios are properly programmed for this test.
Once the endpoint is receiving the RTK data and the terminal is displaying this transmission, disconnect the radio from the computer and power. Change the endpoints 5 pin x 2 pin routing jumper to the TTL side so that the signals are routed to the D9 serial port.
Next, connect the Navspark rover’s GND to the Freewave endpoint’s D9 GND (pin 9) and the Navspark RX2 to the Freewave endpoint’s TXD (pin 2). Power on the Navspark GPS by connecting the mini USB connector to your computer. Open up the GNSS Viewer to see the GPS position data in real time. Then power on the Freewave.
Within the GNSS viewer you should be able to see the GPS position measurement go from 3D position fix to differential GPS to RTK Float to RTK Fix within a few minutes. Once the position reading is RTK float you can be certain the Freewave radios are connected and working properly.
If you can’t get a RTK position, here are a few things to try:
Make sure the base’s antenna has not been moved since being turned on. Just power cycle it to have the base resolve a new fixed location within a couple of minutes.
Check that the GPS can get an RTK position reading with the hardwired serial connection shown in the Napspark Getting Started guide.
Make sure that the freewave radios are configured properly.
Program the GPS rover serial port baud rate to be 115200. Program the GPS base serial port baud rate to be 115200.
OPEnS House 2019 was a public event where academics from Oregon State University and industry professionals interested in environmental sensing could check out some awesome projects, ask questions and get a better idea of some of the research going on within the lab.
For the event the SlideSentinel team decided to get a working demo up and running to showcase the system so far. This demo provided the perfect opportunity to integrate working components into a single coherent system.
To set the demo up the team deployed the hub on top of OSU’s Weiniger Hall. The Hub contained the RTK GPS module, the Freewave Z-90 for receiving NMEA strings from the rover and the Adafruit FONA 808 for making HTTP requests to the PushingBox API capable of logging the rover locations in realtime to a Google spreadsheet. The total distance between the hub and rover was roughly 1000ft. This was super exciting news as the link travelled through multiple concrete buildings and data was still being received by the hub, intact and at a consistent rate.
The Rover for the demo featured a relay module tired to a real time clock and accelerometer. Upon substantial orientation change or movement the accelerometer would flip the relay to power the devices, and the Rover would attempt to get an RTK fix and begin sending NMEA strings to the hub. For a better visual representation of the system the team logged the coordinates on the Google spread sheet to a Google map in real time.
The demo went incredibly well and it was super exciting to see all of the components working together! During the live demonstrations team members would take the rover and go on a brief walk, and spectators could observe as the rovers location was logged live to the Google map in real time.
The OPEnS house was an awesome opportunity to showcase some of the work that has gone into this project. The team met multiple other researches and academics interested in the technologies we are developing and are looking forward to a live deployment in March.
ROCKBLOCK is an out of the box satellite communication module manufactured by Rock7. The device is constructed to interface with embedded microprocessors such as Arduino’s and Raspberry Pi’s. What makes the ROCKBLOCK such an incredible device (and also an appealing tool for the SlideSentinel project) is the fact that it can send Short-Burst Data (SBD) through the Iridium Satellite constellation, an aggregate of 66 active satellites used for worldwide voice and data communication. This means that projects using the ROCKBLOCK satcom module can send and receive data from a basestation from just about anywhere on the surface of the Earth that is exposed to the open sky.
Due to the remote nature of the SlideSentinel deployments and potential weather hazards, the team has opted to use the ROCKBLOCK module for sending data from the base node to servers where it can be further processed and recorded via Google spreadsheets.
The ROCKBLOCK+ exposes a 7 wire interface
9-30 VDC input
On/Off control (sleep pin)
Ring Alert Indicator
For simple use cases involving synchronously sending data, the only needed pins are the RX and TX lines, however the On/Off control pin, Ring Alert Indicator, Network Availability offer useful functionality which merit discussion. The ROCKBLOCK+ has an internal super-capacitor which requires roughly 10 seconds to charge. Once charged the module can begin sending data. If you are constructing a time critical application the On/Off control pin puts the module into a “sleep” mode, in which minimal power is consumed to maintain the super-capacitors charge. This allows the module to wake up quickly (perhaps due to an interrupt) and skip the 10 second capacitor charge wait before sending data.
The ring alert indicator is an active low output from the ROCKBLOCK+. When the voltage on the pin goes low there is a in incoming message in the MT queue which can be read by the module. This pin is useful for bidirectional communication with the module.
Finally the ROCKBLOCK+ presents an active low network availability pin. When the ROCKBLOCK+ module is on, the device periodically polls for an available Iridium satellite connection. If such a connection is found there is a high likelihood that data can be sent and received by the device and the network availability pin will go low.
For the official developer documentation on the ROCKBLOCK module follow this link.
All outputs and inputs to the ROCKBLOCK+ must present RS232 voltage levels. Thus if communicating with the module with a TTL device an RS232 level shifter must be used. In the case of the SlideSentinel project the Adafruit Feather is used to send AT commands to the module. For testing the module on a breadboard we used the MAX3232 IC, which convert 3.3 volt TTL to RS232 and has two line drives and receivers. This linked article provides a concise explanation on the RS232 standard.
In order to receive the network availability, On/Off, and ring indicator signals an RS232 level shifter with at least four receive lines is required. For the SlideSentinel PCB interface to the ROCKBLOCK+ we decided to use the MAX3242 IC which presents 5 receive lines and 3 transmission lines.
With the RS232 interface configured the last step is sending AT commands to the module. The IridiumSBD is a convenient library for interfacing with the modem. Below are three photos depicting the a serial output from an Arduino script which communicates with the ROCKBLOCK+, a picture of the probed RS232 UART signals between the Arduino and ROCKBLOCK and the PCB designed to interface with the module for the Adafruit Feather. The Arduino script asks the module for its firmware version, then is asks the module for a number between 0-5 indicating signal strength and finally sends an AT command which transmits the string “Hello World.”
Configuring the Freewave Z9-T DEVKIT radio can be at challenging at times, so this is a post meant to supplement the Freewave setup guide. This blog is not intended to cover all of the elements of setting up the radios, but instead to cover some gaps that may exist within the documentation.
The quick start guide can be found at Freewave’s Support Website. Their support website requires registering a free account with your email. A full user guide is also available for the Z9-T DEVKIT and for the Z9-T radio in the ZumLink 900 Series tab of the support website.
It is likely easiest to use the terminal interface tool Tera Term. This is what the quick start guide uses, and it is what the author used to configure the radios. Tera Term can be downloaded here. However, if you are using a unix system, use PuTTY instead to open a USB serial connection to the radios.
Now, let’s get started with setting up the radios. You should have both this blog and the quick start guide open at the same time for best results.
Connect the antenna to the radio without any power or other connections.
Ensure the 5 pin x 2 pin jumper on the devkit is connected on the USB side of the pin block and NOT on the TTL (D9 Port) side.
Connect the provided 12V power cable.
Connect the micro USB serial cable between your computer and the Freewave radio. Take note of the COM port that was added, this will be used in the CLI configuration.
Follow the CLI configuration steps provided in the quick start guide. Be sure to press the S1 interrupt button on the radio every time a new terminal setting configuration is attempted (CLI configuration step 8). If you do not press the S1 interrupt button on the radio before sending enter in the terminal tool, the radio will not connect. Here is an example of the correct setup steps:
Select a new baud rate in the serial port setup pane.
Accept new configuration.
Press the S2 interrupt pin.
Press enter in the terminal window. If the shell does not return a new line with “>” at the line head, the serial port is not configured correctly, go back to step 1 and try another configuration.
The quick start guide steps are for programming the radios out of the box, and the configuration settings may have been changed by another developer, so here are a few common configurations to try if the Freewave CLI is not connecting.
Try a different BAUD rate.
A baud of 115200 is most common, and 3000000 (three million) is also common and used for uploading new firmware.
Available CLI BAUD rates are 9600, 19200, 115200, 230400, 460800, 921600, and 3000000.
Try turning flow control off.
The two available flow control settings for the radios are Hardware (ACK/NACK for PuTTY) and off.
If flow control is turned off, the most likely BAUD rate is 115200. This setting is used with the NavSpark GPS for the Slide Sentinel project.
Try a different serial port or plug and unplug the USB connected to the devkit to make sure you are using the right port. Be sure that you are using a micro USB data cable.
The data, parity, and stop bits are unlikely to change based on our lab’s current usage, however check the data format of the last use case if you still can’t get the radio to connect to the CLI tool.
Unfortunately no TerraTerm port exists for OSX or Linux distributions. If you are using a machine running these operating systems you will need to use an alternative application for establishing terminal serial connections and configuring Freewave Z9-T.
First, plug in the device and determine if your machine recognizes the Freewave Z9-T development kits, open a new terminal and run:
$ ls /dev/cu.usbserial*
The above command will list all usb serial devices connected to you machine, these devices show up in /dev directory. If a Freewave developer kit is connected and recognized you should see the terminal return something like this:
The easiest way to establish a serial connection to the device and enter the Freewave shell is using the screen command line tool. Run the below command to verify that you machine has the tool installed.
$ screen --version
If you receive the following error “-bash: screen: command not found”, then you must install the tool by installing it:
$ brew install screen (mac)
$ sudo apt-get install screen (Linux)
With screen installed, a serial connection can now be created. In a terminal window type the following command:
$ screen /dev/cu.usbserial-DEVKIT 115200
Press the interrupt button on the Freewave development kits then enter the screen command. If all goes well your terminal will go blank. Simply hit enter twice and you will be prompted by the Freewave shell. Proceed to “Using the Freewave Shell Command Line Interface” section for configuring the radios properly.
Use of the shell is not covered in depth within the quick start guide, so here are some helpful tips for using the shell.
Press tab at any time to auto complete a command or show all available commands.
Typing a specific command or group of settings will allow you to see the current value(s) for those settings. Try typing “serialPortConfig” to see the current serial port settings. Make note of these for the next time you need to connect to the radios.
Typing “radioSettings” will show the current radio configuration.
The shell is not case sensitive, no need to worry about case.
To change a value, just type “fakeValue=x” for instance cliBaudRate=115200 will update the baud rate that is used for connecting to the freewave shell.
If you want to know all the available values for a setting, type “fakeValue=” and press tab to show all the available values.
More description on settings is contained in the Z9-T user reference manual, here.
The quick start guide provides all the settings necessary for connecting two radios with a wireless link. One setting that could not be changed was the “radioSettings.maxPacketSize” setting. Attempting to change this will always return “RESULT 20: SETTER NOT VALID” however this is not an issue as long as both radios have the same value for maxPacketSize.
Note that you must update the firmware of each radio if it is not up to date. The firmware update guide is in the Z9-T user reference manual, section 8.
When first attempting to connect and send a file via a radio link, follow the data logging steps provided in the quick start guide using this copy of Alice in Wonderland as the test file. It has no <CR> or <LF> characters which cannot be used by the terminal logging software. Once the radios have been configured correctly for the data transfer, start the log on the gateway terminal. And send the file using the Tera Term send option from the terminal connected to the Endpoint.
Be sure that neither terminal is connected to the Freewave shell, this will prevent data transmission.
A successful transmission will show text flowing in both terminals, and the log will be accumulating data. Once transmission is complete, stop logging. Run a file comparison (FC command in windows command prompt) to ensure data was transmitted without error.
NOTE: ensure that you have updated the firmware on the radio and “radioSettings.maxPacketSize” is configured to the same value on both radios as detailed in the above section. These configuration steps do not differ between Mac/Linux and Windows.
In order to send a message between the two radios you will need to exit the Freewave shell on both the Gateway and Endpoint. From the Freewave shell connections type:
Hit enter. Then press the reset button on the dev kit boards.
Download the copy of Alice in Wonderland, and ensure you know the full path to the file.
Now from the terminal which previously held a connection with the Freewave Z9-T configured as a Gateway enter:
Ctrl + a
Then enter a colon like so,
The above sequence of keystrokes signals the screen tool that you are going to enter a command. In order to send the file we need to first load the copy of Alice in Wonderland into a buffer. To do this run:
readreg p /path/to/Alice/In/Wonderland
The terminal should return the following statement:
Slurped X character into buffer
Now we are ready to send the file. I recommend having the terminal window connected to the Freewave Endpoint in visible sight so you can see the file contents printed to stdout as the Endpoint receives the file. To send the file to the Gateway type the input command signal Ctrl + a and : (colon) then enter:
You should see a steady stream of data printed to the terminal window connected to the Endpoint Freewave. Congratulations you just transferred Lewis Carrol’s Alice in Wonderland across the air between two Freewave Z9-T’s!