Indigresso Wiki

Open Source Stuff for DASH7

User Tools

Site Tools


opentag:api

OpenTag API

OpenTag supports an API that offers programmability on the Server-side as well as the Client-side. There are four primary components to the API: C API, ALP API, DASHForth, and Logger. In addition, the Veelite filesystem module has its own API, which can be used with C or ALP.

API Programming & I/O Model

The API is separated into a Client-Server I/O Model, where certain components are suited to usage on the client, others on the server, and then there is DASHForth (which is difficult to classify).

To describe the concept, the “Client” is typically the heavier of the two hosts, often a PC or smartphone or something like that (OpenTag prefers POSIX-based clients). The “Server” is typically something like a microcontroller+RF system. This definition of client and server is consistent with the formal way it is used in POSIX systems, where the server is the agent and the thing that is managing the datasources. A complete, OpenTag application requires at least a Server, and optionally a Client as well.

Server-only

Attributes: Remote, automated devices with DASH7 I/O only (DASH7 language: Endpoints, Subcontrollers).

Capabilities: Automated responding to requests, automated beaconing, application-driven communication and storage of other datasources.

Available API features are: C API, Server-side DASHForth programs

Server+Client

Attributes: A DASH7 stack (server) bridged with a client stack (DASH7 language: Gateways). The client stack may have its own methods of I/O or automated intelligence.

Capabilities: Automated responding to requests, automated beaconing, application-driven communication and storage of other datasources, logging stored or received data to client, client-driven application requests.

Available API features are: C API (server-side), DASHForth programs (server-side or provided by client as applet), ALP API directives (provided by client as message), Logger (server-to-client data dumping).

API Component Manifest

Compilations of OpenTag may include no API components at all, for size-optimized remote devices, or some assortment of available API components. OpenTag is written and architected such that the API components incur a minimal overhead, although removing them can save program memory on the server. Posted in the table below are approximate build sizes for components related to the API. The reference was TI CC430 compiled with CCS using no compiler optimization. Using speed optimization tends to bring build size down by about 3%, and using size optimization tends to bring build size down by about 6%. These metrics are also relevant to the Cortex M3, which also uses a 16 bit instruction set, and in my experience it builds into very similar size as the MSP430.

API Component Approx Build Size In Versions Comments
NDEF 0.4 KB 1.0+ NFC Data Exchange Format (a data wrapper protocol)
MPipe 0.5 KB 1.0+ Requires NDEF
C API wrappers 0.7 KB 1.0+
ALP Core 0.3 KB 1.0+ Required for ALP-API (usually wireline only) or DASH7 ALPs (wireless or wireline)
ALP-API + File ALP 2.4 KB 1.0+ ALP-API requires NDEF and MPipe
Logger 0.1 KB 1.0+ Requires NDEF, acts like “Echo” when used as an ALP.

As you can see, a complete implementation of all API components yields a program memory overhead of about 4.4 KB (for MSP430 or Cortex M3). The SRAM overhead is negligible, typically less than 32 bytes or so, and it is mostly tied to MPipe. Lightweight OpenTag devices may not need to use any of these components.

C API

C API Main Article
The C API is just callable C functions, each of which is a simplified wrapper for a sequence lower-level OTlib functions. The C API can be used to build requests, create events, and do some other sandboxed features that are part of OpenTag's standard OTlib functionality (in other words, if you are an OpenTag kung-fu master, you can just call the OTlib low-level functions directly to get the same effect). That said, the C API functions are cleaner and simpler to use, and just as good if you don't need the deepest level of functionality.

ALP API

ALP API Main Article
ALP is a general OpenTag term that means “Application Layer Protocol.” OpenTag / DASH7 specify the usage of Application Layer Protocols for certain over-the-air features. The same ALPs that are available to DASH7 are also available to wireline or interprocess messaging – this messaging channel is called the MPipe, and it can be implemented in almost any way (see section on MPipe. In addition, there are some ALPs that directly map to the C API, and these can only be used with Mpipe (but not via DASH7 over-the-air).

DASHForth

DASHForth is a Forth toolchain designed to work especially with DASH7 and OpenTag. It is currently in development. It won't be ready for some time, but when it does arrive, it will allow revolutionary capabilities. One way to think of DASHForth is as a method for writing shell scripts that OpenTag runs, although it goes a bit deeper.

The value of DASHForth is the ability for it to add metaprogramming to API functions. The ALP API is a very optimized message-based API (i.e. a command and control protocol), but it still cannot accommodate metaprogramming. As a result, the client is forced to spend a lot of energy reading-in ALP responses and deciding what to do next – most API designers and user accept this architecture as a fact of life, but it doesn't have to be. DASHForth can embed data manipulation and process control directly into the API directive stream, thereby dramatically reducing the amount of parsing and processing that has to occur on the client between API calls.

Logger

Logger Main Article
The Logger echos to the MPipe whatever data is sent to it. Most Logger functions are only available through the C API (they are defined in OTAPI_c.h and implemented in OTAPI_logger.c). However, ALP usage of the Logger is permitted, and it maps always to otapi_log_raw().

Logger functions do not apply the C API general form because they are special purpose functions that do not link to ALP or DASHForth (except for otapi_log_raw(), which behaves like echo).

NDEF

NFC Data Exchange Format (NDEF) is developed by the NFC Forum for use as a message-based API and data transfer mechanism for NFC solutions. From and API standpoint there is a lot of similarity between NFC and DASH7, so it made sense for OpenTag to include NDEF support, and it would also be cool to see NFC devices themselves as activators of API functions. Additionally, the folks at Google are committed to maintaining an NDEF interface in the Android API (starting with “Gingerbread”), so allowing NDEF gives OpenTag the possibility to have an Android Client.

Implemented Featureset

OpenTag's NDEF implementation provides a legal subset of the total NDEF specification. NDEF records that do not comply with this rule subset will be ignored. The implementation is part of the NDEF module, defined in /OTlib/ndef.h and implemented in /OTlib/ndef.c.

  • All NDEF Record Types are either UNKNOWN (TNF=5) or UNCHANGED (TNF=6)
  • All NDEF records include two-byte IDs (IDs contain the directive ID and command bytes)
  • All NDEF Payload lengths must be 255 bytes or less, thereby restricting the Payload length field to 1 byte
  • Multi-record messages are supported
  • Multi-chunk records are supported

Architecture Notes

NEDF messages may be transferred over the MPipe. The MPipe can be basically anything (a wire, an interprocess pipe, a wireless connection), but MPipe – and therefore NDEF – assumes that the client on the other side is a valid OpenTag root user (only root can use API functions). So make sure that any NDEF pipe between OpenTag and something else is sufficiently secure.

MPipe

Mpipe is short for “Message Pipe.” It can be thought of as the I/O mechanism for OpenTag's command shell – MPipe is to OpenTag what /dev/tty is to a POSIX system. Also, like with /dev/tty, MPipe can be implemented in an infinite number of ways. The Mpipe definition is in /OTlib/mpipe.h and the implementation is in /Platforms/[Platform name]/mpipe_[platform name]_[interface].c. For example, the variant of MPipe that runs over the CC430 UART would be /Platforms/CC430/mpipe_CC430_uart.c.

Some Possible Media for MPipe

MPipe can work over any connection that can transfer two-way data. However, users need to make sure the connection is sufficiently secure to meet their needs. Since the MPipe is always a point-to-point connection, MAC layer encryption with pre-shared keys is a good strategy. Alternatively, if you are using a wire between two chips and you don't store critical information within OpenTag, then it is fine to use no encryption.

  • UART Serial (implemented)
  • USB (implemented via serial converter)
  • SPI
  • I2C
  • Ethernet

Some Possible Protocols for MPipe

MPipe requires a point-to-point MAC protocol. The default implementation uses a very basic, proprietary protocol that assumes 1:1 connection between client and server, and which provides data integrity checks and ACKs. This is suitable for short-distance connections. For longer-distance connections, a more complex MAC Protocol is recommended (PPP is a decent choice).

  • Proprietary (implemented)
  • UUCP
  • SLIP
  • PPP
  • TCP/IP
opentag/api.txt · Last modified: 2011/10/01 01:19 by jpnorair