Skip to content

Latest commit

 

History

History
416 lines (298 loc) · 17.3 KB

README.md

File metadata and controls

416 lines (298 loc) · 17.3 KB
Raw

AGILE Maker's Shield Software

Table of contents

  1. AGILE Maker's Shield Software
    1. Introduction
    2. Installation
    3. Running and exiting the server
  2. AGILE DBus Feature API (iot.agile.Feature)
    1. Features and methods
    2. Usage
    3. GPS
    4. ADC
    5. Atmospheric sensor
    6. LEDs
  3. AGILE DBus Protocol API (iot.agile.Protocol)
    1. Protocols and methods
    2. Usage
    3. XBee 802.15.4 and XBee ZigBee modules
      1. Setup method
      2. Connect method
      3. Send method
      4. Receive method
      5. Disconnect method
      6. Get configuration
      7. Set configuration
    4. LoRAWAN/LoRA module
      1. Setup method
      2. Connect method
      3. Send method
      4. Receive method
      5. Disconnect method
      6. Get configuration
      7. Set configuration
    5. DBus specification

Introduction

This repository contains a Python3 DBus server for the AGILE Maker's Shield. The bus implements two interfaces: iot.agile.Protocol, which exposes communication modules attached to the shield sockets over DBus, and iot.agile.Feature, which exposes the features of the shield, as the GPS, the ADC or the LEDs.

The server is in alpha version, as the AGILE API is being defined.

A folder with examples of use of each of the features and protocols is included.

This repository complements the agile-makers-shield-hardware and the agile-makers-shield-firmware repositories.

Installation

In order to run the application, some DBus libraries must be installed in the system.

sudo apt-get install libdbus-1-dev libdbus-glib-1-dev python3-gi

The python modules required are listed in the requirements.txt file, and can be installed from there.

sudo python3 -m pip install -r requirements.txt

Running and exiting the server

To run the server, execute the src/agile_makers_shield_server.py program. You can set it output log level by passing an argument with -l "LEVEL" to any of the levels of the Logging facility for Python (the more interesting being "INFO" and "DEBUG"). Moreove, there are two ways to connect the modules to the shield. The way there are connected must to be set by passing the argument -s if the shield is plugged or not passing it if it's not plugged.

There are two ways of exiting the server, either by calling the Exit method (prefered) or by using Control+C.

dbus-send --session --type=method_call --dest='iot.agile.MakersShield' '/iot/agile/MakersShield' iot.agile.MakersShield.Exit

AGILE DBus Feature API (iot.agile.Feature)

This part defines how to use the features of the shield.

Features and methods

The shield have the following features:

  • GPS
  • ADC (Analog-to-digital converter)
  • Atmospheric sensor (temperature, humidity and pressure)
  • LEDs

Usage

Each of the features works in a different way, as they are very different to share common functions.

GPS

DBus methods:

  • updateGPS () -> void
  • getLastGGA () -> a{sv}
  • getLastRMC () -> a{sv}

It is neccesary to call updateGPS each time that is desired to get new data. It will update the values of getLastGGA() and getLastRMC(), so when calling each of them separately they will return the values of the same update read.

Both getLastGGA() and getLastRMC() will return its respective standard NMEA frame for GGA or RMC.

ADC

DBus methods:

  • readADC (a{sv}) -> void

Parameters of readADC(a{sv}):

  • "channel": The channel to read from (1-4)
  • "mode": The read mode, "one_shoot" (default if omitted) or "continuous"
  • "resolution": The resolution bits, 12, 14, 16 or 18 (default if omitted)
  • "pga": The programmable gain amplifier, 1 (default if ommited), 2, 4 or 8

Return value of readADC(a{sv}):

  • "channel": The channel read
  • "value": The value of the last read

Atmospheric sensor

DBus methods:

  • readAtmosphericSensor () -> a{sv}

Return value of readAtmosphericSensor():

  • "temperature": The temperature in Celsius degrees
  • "humidity": The relative humidity in percentage
  • "pressure": The pressure in Pa

LEDs

DBus methods:

  • getLedStatus (a{sv}) -> a{sv}
  • setLedStatus (a{sv}) -> void

Parameters and return values of getLedStatus()/setLedStatus():

  • "led": One of the LEDs, each LED has three different names to be referenced (see table below).
  • "bright": Int from 0 to 255 if single color LED (see table below)
  • "color": Int array of RGB from 0 to 255 if RGB LED (see table below)
led (name 1) led (name 2) led (name 3) color bright
0 LED0 S0 ✔ ✗
1 LED1 S1 ✔ ✗
2 LED2 A2 ✗ ✔
3 LED3 A3 ✗ ✔
4 LED4 A4 ✗ ✔

AGILE DBus Protocol API (iot.agile.Protocol)

This part of the protocol defines how the communication with each type of module supported works.

Protocols and methods

The server implements the following protocols:

  • XBee 802.15.4
  • XBee ZigBee
  • LoRaWAN/LoRa (Microchip RN2483)

Each protocol might implement the following methods:

  • Connected () -> string
  • Driver () -> string
  • Name () -> string
  • Connect () -> void
  • Disconnect () -> void
  • Discover (a{sv}) -> void
  • Exec (sa{sv}) -> void
  • Setup (a{sv}) -> void
  • Send (a{sv}) -> void
  • Receive () -> a{sv}
  • Subscribe (a{sv}) -> void
  • GetConfiguration() -> a{sv}
  • SetConfiguration(a{sv}) -> void

Usage

The order of execution for any module is:

  • Setup
  • Connect
  • Send / Receive
  • Disconnect.

The Setup method only applies when the Connect method is called. If no setup parameters are defined, the Conect method may use default parameters.

XBee 802.15.4 and XBee ZigBee modules

Setup method

The Setup method will define the parameters that will be applied to the module. The method accepts the type a{sv} (array of "string: variable" pairs, ie. Python's Dictionary).

These "string: variable" pairs can be:

  • "baudrate": int -> Defines a valid baudrate for the module. If omitted, defaults to 9600.
  • "apiMode2": boolean -> Defines if the module is in API Mode 2. Iif omitted, defaults to false.
  • string atCommand1: string -> Two char string defining the AT command to send, the value must be the string representation of the hex parameter (example: {"ID": "A1B2"}).
  • string atCommand2: string
  • ...

Connect method

The Connect method opens the communication with the XBee module and applies the parameters stored in the setup.

Send method

The Send method accepts the type a{sv} in order to send information through the XBee module.

The "string: variable" pairs must be:

  • "api_command": string -> One of the API Commands of the API Commands table.
  • string field: byte[] -> The fields required by the API Command, whose value must be an array of bytes
  • string field2: byte[]
  • ...
API Command Fields XBee 802.15.4 XBee ZigBee
at frame_id, command, parameter ✔ ✔
queued_at frame_id, command, parameter ✔ ✔
remote_at frame_id, dest_addr_long, dest_addr, options, command, parameter ✔ ✔
tx_long_addr frame_id, dest_addr, options, data ✔ ✗
tx frame_id, dest_addr, options, data ✔ ✔
tx_explicit frame_id, dest_addr_long, dest_addr, src_endpoint, cluster, profile, broadcast_radius, optios, data ✗ ✔

Receive method

The Receive method returns a frame received by the module in the format of a{sv}. The fields of the frame depend on the response and can be check in the API Responses table.

API Responses Fields XBee 802.15.4 XBee ZigBee
(0x80) rx_long_addr source_addr, rssi, options, rf_data ✔ ✗
(0x81) rx source_addr, rssi, options, rf_data ✔ ✗
(0x82) rx_io_data_long_addr source_addr_long, rssi, options, samples ✔ ✗
(0x83) rx_io_data source_addr, rssi, options, samples ✔ ✗
(0x88) at_response frame_id, command, status, parameter ✔ ✔
(0x89) tx_status frame_id, status ✔ ✗
(0x8A) status status ✔ ✔
(0x8B) tx_status frame_id, dest_addr, retries, deliver_status, discover_status ✗ ✔
(0x90) rx source_addr_long, source_addr, options, rf_data ✗ ✔
(0x91) rx_explicit source_addr_long, source_addr, source_endpoint, dest_endpoint, cluster, profile, options, rf_data ✗ ✔
(0x92) rx_io_data_long_addr source_addr_long, source_addr, options, samples ✗ ✔
(0x95) node_id_indicator sender_addr_long, sender_addr, options, source_addr, source_addr_long, node_id, parent_source_addr, device_type, source_event, digi_profile_id, manufacturer_id ✗ ✔
(0x97) remote_at_response frame_id, source_addr_long, source_addr, command, status, parameter ✔ ✔

Disconnect method

The Disconnect method closes the communication with the XBee module.

GetConfiguration method

The GetConfiguration method returns the parameters stored in the setup of the XBee module.

SetConfiguration method

The SetConfiguration method configures the XBee module with the parameters from an a{sv}.

LoRAWAN/LoRA module

Setup method

The Setup method will define the parameters that will be applied to the module. The method accepts the type a{sv} (array of "string: variable" pairs, ie. Python's Dictionary).

These "string: variable" pairs can be:

  • "baudrate": int -> Defines a valid baudrate for the module. If omitted, defaults to 57600.
  • "save": boolean -> Defines if the LoRaWAN parameters will be saved in the module's EEPROM. The LoRa parameters cannot be saved. If omitted, defaults to false.
  • "mode": string -> Defines the mode that the module will be use, posible values are "LoRaWAN" and "LoRa". If omitted, defaults to "LoRaWAN".
  • "join": string -> If the "mode" is "LoRaWAN", this parameter defines how the module will join to the network: "OTAA" or "ABP". If omitted, defaults to "OTAA".

The rest of the setup parameters depends on the "mode" selected.

Mode LoRaWAN (OTAA) LoRaWAN (ABP) LoRa
deveui ✔ Optional ✗
appeui ✔ ✗ ✗
appkey ✔ ✗ ✗
devaddr ✗ ✔ ✗
nwkskey ✗ ✔ ✗
appskey ✗ ✔ ✗
freq ✗ ✗ ✔
sf ✗ ✗ ✔
cr ✗ ✗ ✔
bw ✗ ✗ ✔
crc ✗ ✗ ✔
pwr ✗ ✗ ✔

These parameters are:

  • "deveui": string -> Defines the Device EUI (8-byte hexadecimal number). If omitted, defaults to the parameter saved in the module's EEPROM.
  • "appeui": string -> Defines the Application EUI (8-byte hexadecimal number). If omitted, defaults to the parameter saved in the module's EEPROM.
  • "appkey": string -> Defines the Application Key (16-byte hexadecimal number). If omitted, defaults to the parameter saved in the module's EEPROM.
  • "devaddr": string -> Defines the Device Address (4-byte hexadecimal number). If omitted, defaults to the parameter saved in the module's EEPROM.
  • "nwkskey": string -> Defines the Network Session Key (16-byte hexadecimal number). If omitted, defaults to the parameter saved in the module's EEPROM.
  • "appskey": string -> Defines the Application Session Key (16-byte hexadecimal number). If omitted, defaults to the parameter saved in the module's EEPROM.
  • "freq": string -> Defines the Frequency value. Valid values go from "433050000" to "434790000" and from "863000000" to "870000000", in Hz. If omitted, defaults to "868100000".
  • "sf": string -> Defines the Spreading Factor value. The valid values are "sf7", "sf8", "sf9", "sf10", "sf11" or "sf12". If omitted, defaults to "sf12".
  • "cr": string -> Defines the Coding Rate value. The valid values are "4/5", "4/6", "4/7", "4/8". If omitted, defaults to "4/5".
  • "bw": string -> Defines the Bandwidth value. The valid values are "125", "250" or "500", in kHz. If omitted, defaults to "125".
  • "crc": string -> Defines the use of CRC. Valid values are "on" or "off". If omitted, defaults to "on".
  • "pwr": string -> Defines the power of the module in dBm. The valid values go from "-3" to "15", although the maximum by design is "14". If omitted, defaults to "13".

Example of the setup a{sv}: {'baudrate': 57600, 'save': True, 'mode': 'LoRaWAN', 'join': 'OTAA', 'deveui': '0102030405060708', 'appeui': '0102030405060708', 'appskey': '0102030405060708090A0B0C0D0E0F00'}

Connect method

The Connect method opens the communication with the LoRaWAN module and applies the parameters stored in the setup.

Send method

The Send method accepts the type a{sv} in order to send information through the LoRaWAN module.

The "string: variable" pairs must be:

  • "type": string -> "LoRaWAN" mode only. The type of the frame to send: "uncnf" (unconfirmed, no ACK) or "cnf" (confirmed, with ACK). If omitted, defaults to "uncnf".
  • "port": int -> "LoRaWAN" mode only. The port to use. If omitted, defaults to 3.
  • "data": string -> An hexadecimal representation of the data.

Receive method

Only the "LoRa" mode can receive data. The Receive method returns a frame received by the module in the format of a{sv}. The only field of the frame is "data", and its content is the hexadecimal representation of the data.

Disconnect method

The Disconnect method closes the communication with the LoRaWAN module.

GetConfiguration method

The GetConfiguration method returns the parameters stored in the setup of LoRaWAN module.

SetConfiguration method

The SetConfiguration method configures the LoRaWAN module with the parameters from an a{sv}.

DBus specification

After detecting one of the possible modules in SOCKET_0 or SOCKET_1, a Dbus signal is sent over Dbus to the corresponding interface name and object path. The signal include the configuration parameters in its arguments.

The interface name in all the cases is BUS_NAME = iot.agile.Protocol . The object path changes depending on the module and the socket where it has been detected:

  • Xbee 802.15.4
    • iot/agile/Protocol/XBee_802_15_4/socket0
    • iot/agile/Protocol/XBee_802_15_4/socket1
  • Xbee ZigBee
    • iot/agile/Protocol/Xbee_ZigBee/socket0
    • iot/agile/Protocol/Xbee_ZigBee/socket1
  • Xbee LoRaWAN
    • iot/agile/Protocol/LoRaWAN/socket0
    • iot/agile/Protocol/LoRaWAN/socket1

Regarding the arguments included in the sending of the signal are the following in this order: BAUDRATE, DATABITS, STOPBITS and PARITY. The values each one of them can take and the correspondence with the configuration parameters are the following:

Value received in the signal Value of the configuration parameter
Baudrate 600 600
1200 1200
2400 2400
4800 4800
9600 9600
19200 19200
38400 38400
57600 57600
115200 115200
Databits 0x00 5
0x02 6
0x04 7
0x06 8
Stopbits 0x00 1
0x08 2
Parity 0x00 None
0x20 Even
0x30 Odd