GAPI Overview

MMB's Gateway API (GAPI) is a set of Java-based software and services built around our RapidConnect firmware. GAPI adds another layer of abstraction on top of our firmware, further simplifying the development of your gateway application (i.e. network coordinator, in Zigbee terminology).

For example, any machine running Java (including the RapidConnect Gateway) can use GAPI to easily do the following:

• Configure a RapidConnect Module, RapidConnect USB Stick or RapidConnect Gateway as a Zigbee Network Coordinator.
• Form a Zigbee network and permit Zigbee HA 1.2 or Zigbee 3.0 devices to join and be discovered (see list of currently supported device types here).
• Interact with devices over the network using simple methods or a simple command line interface provided by the GAPI Sample Application.
• Test specific Zigbee device and coordinator use cases without writing any code using the GAPI Sample Application and its command line interface.

GAPI Benefits

• Guaranteed interoperability and compatibility with Certified Zigbee HA 1.2 and Zigbee 3.0 devices.
• No need to have in depth knowledge of the Zigbee specifications or MMB's low level RapidConnect Serial Protocol.
• Interact with devices on the network at the highest level of abstraction possible.  GAPI will provide instances of Device objects to work with.  For example, LightDevice or ThermostatDevice which will provide convenient functions like LightDevice.on() or ThermostatDevice.readMode().  See more at the GAPI API documentation.
• Focus your time and resources on higher level application development, eliminating the need for embedded systems expertise.

Guide to Gateway Components

1) Host Processor

The MCU or MPU in your IoT Gateway. It must be capable of running Java v1.8 or higher. In MMB's RapidConnect Gateway, the Host Processor is a Marvell Armada 370.

2) RapidConnect Hardware

This is the hardware that provides the wireless radio to communicate with other devices via Zigbee. If you are using our RapidConnect Gateway, the RapidConnect hardware is built-in. If you are building your own gateway, you can add any of our RapidConnect hardware. Many of our customers start their integration with a USB Demo Board while their hardware design team builds a gateway PCBA with the RapidConnect Module on board.

3) API

The set of methods that are available via GAPI. We recommend taking a quick look at the Gateway Client and then reviewing the Basic Initialization. You can also use the source code for the Sample Application as a reference.

4) Sample Application

Run this JAR file on your Host processor (i.e. the processor that you have connected to RapidConnect Hardware, or the Host MCU in the RapidConnect Gateway) to complete a CLI-driven demo of GAPI's Zigbee features. You can begin communicating with third-party Zigbee devices without writing a single line of code. Download the JAR file on the Downloads page and review the Sample Application Startup Guide to learn more.

5) RapidConnect Firmware

All of our RapidConnect hardware ships pre-loaded with our RapidConnect firmware. The firmware provides a simplified interface to exercise all of the features required to communicate with Zigbee devices. If you are using GAPI, you do not need to learn anything about the firmware aside from ensuring that you are using the appropriate version. The GAPI Release Notes show the compatible versions of RapidConnect firmware.

If you would like to update the RapidConnect firmware on your hardware, review the firmware upgrade options here: Firmware Upgrades

RapidConnect Firmware Release Notes and RapidConnect firmware images are available here: RapidConnect Firmware Downloads and Documentation

6) RapidConnect Serial Protocol

The RapidConnect Serial Protocol is the collection of UART messages exchanged between the Host Processor and the RapidConnect hardware.

GAPI is built to provide additional abstraction beyond that which is provided by the RapidConnect Serial Protocol. If you are using GAPI, you do not need to study the RapidConnect Serial Protocol.

Getting Started with GAPI

Pre-Requisites

• Gateway hardware. You can choose from the following options:
  1. RapidConnect Gateway: A turnkey gateway solution. It runs Linux, offers multiple connectivity options, and ships pre-loaded with RapidConnect firmware and GAPI software.
  2. Your own Host Processor connected to RapidConnect hardware. You can use any Host Processor as long as it can run Java v1.8 or higher and communicate with our RapidConnect hardware over USB or UART. You must connect one of the following models of RapidConnect hardware to your Host Processor:
     • RapidConnect Module:If you are building your own gateway, use this module to provide Zigbee wireless communication. It has been field-proven and pre-certified against RF regulatory requirements including FCC, ETSI, and ISED.
     • RapidConnect USB Demo Board: It includes the RapidConnect Module plus a USB transceiver. Even if you plan on eventually integrating RapidConnect Module directly in your PCBA design, the USB Demo Board is a great tool for prototyping, testing and quick product demonstrations.
• Zigbee HA 1.2 or Zigbee 3.0 devices to test against.
  • See the page here for a list of devices that existing customers have used.
  • Alternatively, you can use RapidConnect Desktop in conjunction with another unit of RapidConnect hardware to simulate a common Zigbee device. Follow the instructions here to learn more.

Step 1 - Run the Sample Application to See GAPI in Action

• Follow the instructions in the Sample Application Startup Guide to download the Sample Application and run it.
• The Sample Application will enable you to easily form a Zigbee network and communicate with certified Zigbee devices from the currently supported device categories.

Step 2 - Start Your Development

• Download the latest release of the Gateway API Library here and import it into your Java project.
• Review the following resources:
  • API: A list of all of methods available in the Gateway API Library.
  • Basic Initialization: Additional information showing how to use the methods in the Gateway API Library.
  • Sample Application: Review the source code to see an example of how to use the Gateway API Library in your project.
  • Logging Guide: Learn how to configure the logging of your interactions with the Gateway API Library. This will be helpful for troubleshooting.

Step 3 - Test Against Your Target Devices

• You can start by using other RapidConnect hardware to simulate Zigbee devices.
• You can use the Dimmable Light functionality of a RapidConnect Lighting & Sensor Evaluation Board
• Review the list of Devices Validated Against RapidConnect to see examples of products that you can use.
• When you transition to testing against the real devices, make note of the hardware/firmware version on your samples and ensure that it matches the versions that you expect your customers to use. Remember, vendors sometimes break certain features when they release new hardware/firmware!
• If you are using our RapidConnect Gateway, we have specialized test tools to help with your debugging. Talk to your Account Manager to learn more.