Thursday 7 January 2021

Montana: Granite Software resources installed

In order to develop the Montana Granite Litems, a set of software resources are needed. Specifically, for developing the source code for the Arduino Nano 33 IoT, this software has been installed:

  1. Arduino IDE for Mac in its latest version (1.8.13)
  2. Support for Arduino SAMD Boards (32-bits ARM Cortex-M0+) in its latest version (1.8.11)
  3. ArduinoBLE library in its latest version (1.1.2)
Since, from a Bluetooth BLE perspective, the Litem is being supporting the role of GATT server, a GATT client is necessary to exchange data. In real world that client will be the Montana Yellowstone gateway, but in order to decouple litem and gateway developments a basic GATT client will be developed in the  Montana Granite project with the purpose of validating results.

The Granite GATT client will be developed in C# running on .NET Core Framework. For that purpose a VirtualBox Linux host with Ubuntu 20.04 Minimal Desktop distro has been deployed, and this software has been installed:
  1. packages-microsoft-prod.deb package, that adds Microsoft software repositories as packages sources
  2. dotnet-sdk-5.0 package
  3. Visual Studio Code for Linux in its latest version (1.52.1) via snap (sudo snap install --classic code)
  4. C# Visual Studio Code extension
  5. git package
  6. nuget package
BlueZ, the Linux Bluetooth protocol stack, was included in the Ubuntu distro.

Tuesday 5 January 2021

Montana: Arduino Nano33 IoT selected for Granite project

In order to develop the Montana Granite project, ie, a Litem based on Bluetooth Low Energy communication, a state-of-the-art in technology have been done. Through all the available modules in the market, two seemed the more promising:

Though the first one offered more flash to a lower price, the second one has been chosen by evaluating positively the stability and support of the Arduino products. Moreover, the Nano 33 is slightly smaller than the Expressif board.

A Nano 33 IoT board has been bought, the Arduino IDE has been installed and support to Microchip SAMD based boards has been added as explained here (specifically, the Nano 33 IoT board is based on a Microchip SAMD 21 SoC). 

The board pinout is similar to the previous Nano boards as can be checked here. A good getting-started project, based on the ArduinoBLE library, can be checked here. Lastly, though the BLE UUIDs should be defined as private, the list of assigned UUIDs can be checked here.

Montana projects started

A new branch in the project repository addressed to develop two new subprojects has been created. The new subprojects are:

  • Litem (Mount) Granite project, addressed to develop a set of Litems based on Bluetooth Low Energy (BLE) devices, specifically on Arduino Nano 33 devices. The code is located in the subdirectory SteamProject/software/litems/ble/arduino-nano33/granite of the GitHub repository (direct access clicking here).
  • Gateway Yellowstone (river) project, addressed to develop a gateway developed on .NET Core using BLE as communication channel. The code is located in the subdirectory SteamProject/software/gateways/dotnet/yellowstone/ of the GitHub repository (direct access clicking here). Yellowstone project is intended to be developed in C#.

Tuesday 11 February 2020

Setting the MAC address on a Texas Instrumens CC26x2

The MAC address of the TI CC2652 can be set as factory configuration or as customer configuration.

In the first case, and as stated in the CC26xx memory map, the address value is stored in the Factory Configuration Area (FCFG1), specifically in the registers MAC_15_4_0 and MAC_15_4_1, corresponding to the addresses  0x500012F0 (address offset 0x02F0) and 0x500012F4 (address offset 0x02F4).

In the second case (address set as customer configuration) the values are stored in the Customer Configuration Area (CCFG), specifically in the registers IEEE_MAC_0 and IEEE_MAC_1, corresponding to the addreses 0x50004FC8 (address offset 0x1FC8) and 0x50004FCC (address offset 0x1FCC).

Though in both cases the values stored in these addresses are read-only at runtime, the values stored in the Customer Configuration Area can be set in the firmware source code. By default, the CCFG IEEE_MAC_0 and IEEE_MAC_1 address values are defined in the Core SDK driverlib startup_files/ccfg.c file, and therefore set for all the developed applications through the macros SET_CCFG_IEEE_MAC_0 and SET_CCFG_IEEE_MAC_1, both set by default to 0xFFFFFFFF.

As the CCFG documentation states, in case of being set to 0xFFFFFFFF, the IEEE_MAC_0 and IEEE_MAC_1 values must be considered invalid and the FCFG1 MAC_15_4_0 and MAC_15_4_1 values must be used. In practice that means that if the user is not setting an specific MAC address, the default, factory MAC address will be used. This behaviour is coded in the main.c of most (fi not all) SDK examples.

Then, how the user can set the MAC address to an specific, user value? To do that, the macros SET_CCFG_IEEE_MAC_0 and SET_CCFG_IEEE_MAC_1 must be re-defined in the application-specific ccfg.c file. This file is empty by default and its purpose is, specifically, redefining CCFG macros with custom-user values. Specifically, SET_CCFG_IEEE_MAC_0 contains bits 31 to 0 of the MAC, whereas SET_CCFG_IEEE_MAC_1 contains bits 63 to 32.

Have in mind that the CCFG area will be only flashed if, apart of stating specific values as previously explained, the debugger flash settings are set to rewrite (not to keep) it. To proceed in that way uncheck the CCFG protection as shown in the image below. Have in mind that, once the user address was writen in CCFG, it is not necessary rewriting it every time the program changes, unless the whole address changed.


Last but not least, it is very important to consider that, in case of defining a user-specific MAC address, it must be considered as local (not universal) and therefore the second-least-significant-bit of the first octet must be set to 1. That means that the least significat byte of SET_CCFG_IEEE_MAC_0 must have its second bit set to 1 (for instance being set to 0x00000002).

If a Texas Instruments reserved universal MAC address is being used (converting it to local according to that explained in the previous paragraph), a list of the TI vendor-specific three first octects can be checked here. Notice that, since they are universal and not local, all the shown values have the second bit of the least significant byte set to 0.

As an example, if the reserved 0xFC0F4B universal address prefix is being used, first it must be converted from universal to local by setting to 1 the second bit of the least significant byte. In that way, the prevouls value would be converted to 0xFE0F4B. Taking it as base, a valid, local MAC address would be FE:0F:4B:00:00:00:00:01. Therefore, the SET_CCFG_IEEE_MAC_0 macro would be set to 0x004B0FFE and SET_CCFG_IEEE_MAC_1 would be set to 0x01000000.

Monday 4 March 2019

Colorado: Accessing to 802.15.4 networks from Raspberry Pi. Software

Raspberry Pi + Digi Xbee + Java integration
This document defines the procedure, from a software perspective, for accesing to a 802.15.4 network from a Raspberry Pi using a Digi Xbee module. This document completes the analogue document defining the procedure from a hardware perspective.

Once successfully completed the hardware integration between a  Raspberry Pi B+ board and a Digi XBee S1 Pro 802.15.4 module, it is necessary to perform some actions addressed to allow the software running on the RPi to access the 802.15.4 network. Since the XBee module is running as PAN coordinator, some of the actions must be addressed to support this additional requirement.

As said in the hardware document, the RPi has a serial port suitable to be used for creating a TTL-level connection with the Xbee module. In the Raspberry versions prior to version 3, this port was /dev/ttyAMA0, however when Bluetooth functions were added the AMA0 was used for Bluetooth and the simpler and more troublesome mini-uart was in charge of the serial connections. So in case of having a RPi 3 and wanting to switch back to the AMA0 serial port (very recommended), it is necessary to edit the /boot/config.txt file and add a new line with the directive dtoverlay=pi3-miniuart-bt.

Another potential problem present in the RPi regarding the usage of the serial ports is the fact that the Linux kernel is configured by default to attach a console to /dev/ttyAMA0. That means that, when booting, the kernel will write to the serial port what could set (and actually does) the Xbee module in a unstable status. To avoid the kernel using the serial port, edit the file /boot/cmdline.txt, that contains the argument list passed to the kernel, and remove the argument console=serial0,115200 or console=ttyAMA0,155200. Take special care in just removing that argument and its preceding or traling space to keep the agument list format coherent.

At this point the RPi is ready to use the XBee module connected to its /dev/ttyAMA0 serial port. To do that from a software point of view, the chosen approach is developing Java code due to several reasons:
  • Java is supported by Raspbian, specifically the JDK8. To install it, run sudo apt-get install oracle-java8-jdk.
  • You can access the serial port from Java using, among other options, the RxTx library. To install it, run sudo apt-get install librxtx-java.
  • You can access the GPIO input/outputs from Java by using the Pi4J library. Specifically, you can use a GPIO output to hard-reset the Digi module, a very interesting option when even the soft reset fails (and it does). To know more about how to control de GPIOs check this example, and to know how to install Pi4J, click here. How to reset the XBee from a RPi GPIO output will be covered in future documents.
Last but not least, you can programatically interface with Digi XBee devices by using the Digi XBee Java Library, whose source code and binaries are available on GitHub and whose complete documention is available on the Digi site. This library offers a high level interface for managing the XBee modules, both as 802.15.4 end points or coordinators. At least up to the last available release (1.2.1) this library relies on the Java RxTx library for accessing the serial port, so it is necessary to install it to allow the library run (see the previous notes about how to install the RxTx library).

First test

Once the XBee Java library is installed on a development computer (that can or cannot be the RPi), a good starting point is following the “Building your first XBee Java application” tutorial described in the library documentation, and doing it taking as base the ReceiveDataSample example contained in the examples/communication subdirectory. This example writes in the standard output all the data (in hex and ASCII format) received from any 802.15.4 end node. To properly run this example, it is necessary to follow these steps once the project has been successfully loaded in the development environment (Eclipse, Netbeans, ...):
  1. Modify the values of the variables PORT and BAUD_RATE declared in the main function, that store the name of the serial port (set PORT to “/dev/ttyAMA0”) and baud rate (set BAUD_RATE to 115200) used to connect to the XBee module.
  2. After successfully building the project, copy the contents of the project subdirectory dist (in Netbeans, the subdirectory where the binaries and libraries are stored after building) to a directory in the RPi (for this example we will assume that it will be copied to the destination directory /tmp/receiveDataTest in the Raspberry Pi)
  3. To run the generated .jar package successfully, It is necessary to tell Java where the native libraries for accesing the serial port (ie, the RxTx libraries) are stored. Specifically, it is necessary to set the system property java.library.path to /usr/lib/jni by calling java with the argument -Djava.library.path=/usr/lib/jni
  4. Due to a known bug in the RxTx library (at least in version 2.1.2), it will not be able to open /dev/ttyAMA0 by itself when running the generated example. To avoid it, set the Java system property gnu.io.rxtx.SerialPorts to /dev/ttyAMA0 by calling java with the argument -Dgnu.io.rxtx.SerialPorts=/dev/ttyAMA0
  5. It is necessary to grant the user running the example permissions to access the serial port. For that purpose, the user must both belong to the dialout group or run the program with root permissions (sudo).
Overall, run the generated example with the command line:

java -Djava.library.path=/usr/lib/jni \
-Dgnu.io.rxtx.SerialPorts=/dev/ttyAMA0  \
-cp /tmp/receiveDataTest/lib:. \
-jar /tmp/receiveDataTest/Xbee.DataReceive.jar

By running the previous command, the Java application launcher will run the file /tmp/receiveDataTest/Xbee.DataReceive.jar (or whatever was the name of the jar file generated when building the project) using the libraries stored in the subdirectory /tmp/receiveDataTest/lib with the suitable values for the system properties java.library.path and gnu.io.rxtx.SerialPorts as previously explained.

It is possible to get a warning message telling about a version mismatch between the RxTx installed version and that used when building the example, but it should not be a problem for starting watching frames in the console as soon as any 802.15.4 end node sent information.