Indigresso Wiki

Open Source Stuff for DASH7

User Tools

Site Tools


opentag:main

OpenTag

OpenTag is a DASH7 Mode 2 software stack, written in C, that is designed with the intent of running on microcontrollers (or radio SoC's). Therefore, OpenTag must be a very tight, compact package, but with proper configuration it can also run in any POSIX environment. It is also worth noting that OpenTag can provide all functionality required for any type of DASH7 Mode 2 device, not just a “tag.”

Code Archives & Licensing

Current and future versions of OpenTag are open sourced under the OpenTag License, which is an outgrowth of the BSD License we designed for standards-based embedded projects (such as OpenTag). OpenTag code & app distributions are available from various places on the internet, and the Archive Page hopes to track all of them.

Doxygen Documentation

Doxygen Main Article
OpenTag uses Doxygen syntax so that automated, Doxygen documentation can be generated.

Interface/API Documentation

API Main Article
If you are a systems developer interested in treating OpenTag like a black-box and going straight to the API, you can skip most of the other documentation and focus on the APIs. You may also want to look at available platforms, boards, and the system architecture section below. There is also an API quickstart guide that is especially helpful for new users starting to work in a client-server system.

System Architecture

System Architecture Main Article
OpenTag is defined as a client-server model with a distributed dataset. A device that runs OpenTag (typically a microcontroller) is a server, and servers communicate with other servers via DASH7. Servers communicate with clients via one of the OpenTag API's or ALP's. Clients are typically POSIX devices like PC's, smartphones, higher-function embedded devices, etc. A device that contains a server and a connection to a client is known as a “Gateway.” Devices that contain only a server are known as “Subcontrollers” or “Endpoints,” depending on configuration and featureset.

Code Architecture

OpenTag is organized as a root directory (known as OTroot or OT root) and a group of subdirectories. Each main subdirectory should contain code (or further subdirectories) related to specific purposes. As well, these subdirectories provide a good organization method for making chapters in the OT users' guide (which is integrated into the wiki).

Subdirectory Contents Platform-Independent Variations
apps Applications and demos (project folders) Typically not Opmode Demo, Ping Pong Demo, Query Demo, …
board Configuration headers for supported boards No EM430RF, Chronos, Jupiter, IKR001, etc
otkernel Scheduler and System Calls Yes GULP, BigGULP, HICCULP
otlib Core library interfaces and code modules Yes No options (flat code)
otlibext Official otlib extensions & patches Typically Yes Application protocols, stub-functions, applets, etc.
otplatform Drivers, utilities, and kernel subroutines No CC430, MSP430, STM32F, STM32L, etc
otradio DASH7 Mode 2 Radio Driver No CC430, SPIRIT1, SX1231, etc
otstack DASH7 Mode 2 Stack for OpenTag Yes No options (flat code)
otulip Ethernet/IP networking for OpenTag Partial

Built-in Applications

OpenTag comes with a set of applications that developers can compile with OpenTag (one at a time) for demonstration, evaluation, or even potentially productization. Each one of these applications is stored in a subdirectory of the /Apps directory (each application may have sub-applications or variants). If you are an application developer looking to spin-out a quick demo, this is a good place to look first.

Board Support

OpenTag is entended mainly for embedded targets, and it supports many “boards” (i.e. circuit boards containing at least a processing element, memory, and a radio). Boards are organized by platform (typically microcontroller families). Each Board platform may be supported by many different board configuration files.

Kernel

OpenTag has a real-time kernel that dispatches tasks when events demand them. There are two kernel options: GULP (Global-interrupt Ultra Low Power) and HICCULP (Hardware Integrated Context Control with Ultra Low Power).

  • The tasking mechanism is “tickless.” The scheduler only runs when pre-empted asynchronously (e.g. by a driver) or immediately after a task returns. In other words, the system will sleep continuously until a driver or task needs to run.
  • Tasks are scheduled via a resource & latency-aware priority list, affording a degree of real-time latency lesser than traditional tickless OSes, using task-queue architecture, are able to provide.
  • Extensive low-power features are implemented that require minimal, if any, interactions from the tasks/apps.
  • HICCULP supports cooperative tasking and threads, but it requires certain features in HW not present in all platforms (ARM Cortex M devices can work with HICCULP, MSP430 cannot).
  • GULP supports only cooperative tasking.

OTlib

Most of the DASH7 code itself is implemented in OTlib, a fully platform-independent C library that OpenTag relies on heavily. Also, the API's are implemented in OTlib.

OTlibext

Any extensions to OTlib are stored here. Some examples are security support, advanced routing algorithms, sensor support, or application layer protocols. In all these cases, the library extensions should be backed by some kind of standard that is recognized by the DASH7 Alliance. Proprietary extensions should stay in the app code.

OTplatform

OpenTag defines a standard platform header in OTlib/OT_platform.h and a standard low-level filesystem header in OTlib/veelite_core.h, but different devices will implement them differently. The implementation of the platform and drivers are stored in OTplatform/. Each platform (i.e. MCU family) has its own folder inside OTplatform/.

OTradio

OpenTag defines a standard radio header in OTlib/radio.h which is bound to be implemented differently by different radios. Therefore, each supported radio device gets a folder inside OTradio/ where the drivers and support files are stored.

Putting it all together

If you define you board configuration file correctly, define your application configuration files correctly, and you setup your project (e.g. makefile) to compile the appropriate source code, everything will build and run. There is always going to be some manual effort, because automated configuration tools just don't work well with the huge variety of platforms and radios that OpenTag can support.

Coding Guidelines

OpenTag is an open source project, so contributions to the source will inevitably be made by the community. There are two types of OpenTag codebases:

  • Official codebases: OpenTag builds that are blessed by JP
  • Unofficial codebases: OpenTag builds that are not blessed by JP

Official codebases will be hosted in the main source distribution (sourceforge). Unofficial codebases may be interoperable with official codebases, and they may be made available to the community, just not on sourceforge alongside the official codebases. In order for a codebase to be made official, JP needs to review it and “bless” it as official. JP will bless codebases that meet the Official OpenTag Coding Guidelines, summarized below:

Features Overview

OpenTag (per DASH7 Mode 2) is a monolithic system that encompasses OSI-layers 1-6 and part of 7 as well (the application layer). Because OpenTag is small, targeted at microcontrollers, and open source, there is no practical deficiency in keeping things monolithic: there is no sense in implementing different layers of an embedded WSN technology on anything but an RF transceiver and an MCU (or an RF SoC). In fact, this design strategy enables OpenTag to be much more optimized than are other, typical solutions for active RFID and WSN.

Runtime Configuration

  • Can run on “bare metal” of an MCU
  • Can run as a daemon on an RT-POSIX system (or similar)
  • Can be ported to an MCU-bound RTOS (ChibiOS, FreeRTOS, TinyOS, uCOS II, etc)

Full DASH7 Mode 2 PHY/MAC including:

  • Links: (Mode 2 PHY), (Mode 2 MAC)
  • PN9 and FEC encoding options in HW (if available) or SW.
  • Transparent CRC16 computation in HW (if available) or SW.
  • Support for all defined channels and data rates
  • Single and multi-frame packet support
  • DASH7 Mode 2 double-sample CSMA routine
  • Link-budget packet filtering
  • Automated contention window generation and timeout
  • Automated re-listen window entry
  • Automated sleep and hold scan cycling
  • Automated beacon transmission
  • Upgradability to DASH7 Mode 2 Data Link Layer security features

Complete implementation of DASH7 Mode 2 Network and Transport layers:

  • All basic M2NP addressing modes (unicast, broadcast, multicast, anycast)
  • M2AdvP transmission (flooding) and detection
  • Routing up to two-hops
  • Supports upgradability to multi-hop routing algorithms
  • M2DP Datastream transfer with 5-way handshake
  • All M2QP transport commands
  • NA2P transport dialogs (non-arbitrated two party, i.e. simple request-response)
  • A2P transport dialogs (arbitrated two party, i.e. sequential query)
  • Upgradability to an A3P scheme (not currently in DASH7 spec)
  • AIND, RAIND, RIGD collision avoidance mechanisms

Configurable-depth session stack

  • Configurable at compile-time (typical depth = 4)
  • Allows dialogs to be scheduled in the future
  • Allows dialogs to create follow-up dialogs

3/4/5-way datastream handshaking

  • Large, point-to-point data transfer (TCP-like)
  • Cryptographic authentication
  • Anything else that needs 3/4/5-way handshaking

Lightweight Filesystem

  • Full support for required DASH7 filesystem features
  • root-user-guest permissions model
  • Read/write and create/delete files
  • 16 bit virtual addressing (platform independent)
  • 16 bit word size
  • Upgradable to 32 bit virtual addressing
  • Unique, high-performance software Flash wear leveling algorithm

Built-in Application Layer Protocols

APIs

  • Low-level C functions (experts only)
  • C API for server-side programming
  • ALP-API for client side messaging
  • Future: DASHForth meta-messaging

Platform Features

  • Platform framework is largely abstracted, so porting is typically quick
  • Simple, NDEF-based wireline protocol for console terminals (MPipe)
  • Confirmed support of CC430, Cortex M3 (ARM), and POSIX
opentag/main.txt · Last modified: 2014/02/27 17:59 by jpnorair