Tag Archives: Radio

A First Configuration of the Freewave Z9-T DEVKIT

Posted on by

Author: Grayland Lunn

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.

Hardware Setup

  1. Connect the antenna to the radio without any power or other connections.

  2. 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.

  3. Connect the provided 12V power cable.

  4. 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.

Configuring Your Terminal (Windows)

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:

  1. Select a new baud rate in the serial port setup pane.

  2. Accept new configuration.

  3. Press the S2 interrupt pin.

  4. 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.

Configuring Your Terminal (Mac/Linux)

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.

  1. 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*

  2. 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:

    $ /dev/cu.usbserial-DEVKIT

  3. 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)

  4. 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.

Using the Freewave Shell Command Line Interface

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.

A Basic Connection Between two DEVKITs (Windows)

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.

A Basic Connection Between two DEVKITs (Mac/Linux)

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.

  1. 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:

    exit

    Hit enter. Then press the reset button on the dev kit boards.

  2. Download the copy of Alice in Wonderland, and ensure you know the full path to the file.

  3. 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,

    :

  4. 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

  5. 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:

    paste p

  6. 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!