Indigresso Wiki

Open Source Stuff for DASH7

User Tools

Site Tools


opentag:alpapi

ALP API

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).

Usage of ALP APIs as a Command Shell

ALPs and ALP APIs can provide access to programmatic features of OpenTag, so they may be dangerous to use over the air without some form of authentication and encryption. In specific, using the Filedata ALP can grant access to file data that might not otherwise be available. In official OpenTag implementations, and in accordance with the DASH7 standard, usage of the filedata ALP over DASH7 requires user authentication in order to access data from files that do not allow guest access.

However, usage over MPipe is permitted to automatically log-in the connected client as root. Some OpenTag implementations require authentication over MPipe as well, but many do not, thereby making MPipe equivalent to a root shell. Incidentally, most of the really interesting ALP API usage is going to happen over MPipe. Purposeful communication between client and server is conducted in this manner. For example, when a user wants to access a server's file data from an MPipe connected client, or if he wants to send requests (over DASH7) from this server, he will generally do so by using the ALP API's with MPipe. Certain client programs, such as OTcom, may contain shortcuts for transferring such API/Shell commands, or they may not. If you are interested in using MPipe as a client-server shell, it is recommended to review the OpenTag clients as well as the M2ALP subprotocol specs (links are on this page, below).

Basic Protocol Architecture For All ALPs

ALPs contain certain data elements that can be encapsulated within many kinds of wrapper protocols. DASH7 Mode 2 contains a common formatting for a directive-based application protocol, including several standardized protocols that go with it. This is known as Mode2 ALP, or M2ALP for short. M2ALP's may be used over DASH7 or transparently over the OpenTag MPipe interface. When using MPipe, the M2ALPs must be padded to meet the NDEF specification, although this is trivial because M2ALP is essentially a subset for NDEF. Additionally, UDP-based application protocols can be embedded within M2QP frame payloads. To summarize, DASH7 (and OpenTag) can work with three classes of ALPS:

  1. M2ALPs that are encapsulated within M2QP or M2DP payloads, and always negotiated via M2QP datastream commands.
  2. M2ALPs that are padded for NDEF and used over MPipe
  3. UDP-based application protocols that are encapsulated within M2QP UDP-shell commands.

M2ALP Design

M2ALPs use directives as a data transfer mechanism. Directives can be sometimes very short and dependent on others around them, so they are able to be transferred in batch. A sequence of one or more directives transferred together becomes the M2ALP message. Readers familiar with NDEF will realize that the M2ALP design maps perfectly to NDEF.

M2ALP Used Over DASH7 M2QP/M2DP

When using DASH7 as a medium for transferring M2ALPs, M2QP or M2DP is used to encapsulate the M2ALP data. The M2ALP wrapper, when encapsulated inside DASH7, is structured as the following 4 bytes:

Flags Payload Length ALP ID ALP Command ALP Payload Footer
1 Byte 1 Byte (N) 1 Byte 1 Byte N Bytes (None)

ALP when used with NDEF

When using NDEF, an M2ALP is structured like below something like below. The “Type Length” field is always 0, and the “ID Length” field is always 2. Furthermore, the Payload Length field is restricted to 1 byte and thus any flags that dictate the length of the Payload Length field (i.e. 1 byte vs. 4 bytes) should be set to the 1 byte option. Thus the NDEF header is 6 bytes.

Flags Type Length Payload Length ID Length ALP ID ALP Command ALP Payload Footer
1 Byte 1 Byte (0) 1 Byte (N) 1 Byte (2) 1 Byte 1 Byte N Bytes (None)

Flags Field

The M2ALP Flags field is the same for NDEF or native usage. NDEF includes additional flags that are not used in native (DASH7) M2ALP usage or M2ALP usage over MPipe, however, M2ALP is a parallel subset of NDEF.

M2ALP Flags Field
Message Begins Message Ends Chunk Continues
b7 b6 b5 b4 b3 b2 b1 b0

The M2ALP/NDEF spec can accept multi-frame data exchange. It uses the following fields to manage the data fragmentation aspects. “Message Begins” is 1 at the first frame of the message, else 0.
“Message Ends” is 1 at the last frame of the message, else 0.
“Chunk Continues” is 1 when there is fragmentation of the data payload across two or more frames.

Payload Length

Number of Bytes in the Directive Payload (NDEF Payload Length)

ALP ID

A code (one byte) that references the specific M2ALP this Directive applies (part of NDEF ID). Some examples are: Filedata protocol, Cryptographic exchange protocol. Here are the ALP Directives defined by the DASH7 standard or OpenTag. The ones defined by OpenTag are above 0x80. More ALPs could be added to OpenTag any time, if the need arises. Unused IDs below 0x80 are reserved for use by the DASH7 standard. http://www.indigresso.com/wiki/doku.php?id=alp_file

ID Name Commands Include: Description
0x00 Null Protocol ACK/NACK Does nothing, can be used as a means of ACK
0x01 Filesystem Protocol Veelite Functions Create/Delete, Restore, Read/Write, chmod, get headers
0x02 Sensor Protocol ISO 21451-7 based Sensor configuration via ISO 21451-7
0x03 DASHForth Shell Production/Debug DASHForth Program Data
0x04 Logger Echo Echos directive data to the Mpipe
0x10 Security Protocols Key Exchange Steps Security Key Exchange Protocols (in development)
0x11
0x12
0x13
0x80 Session API Session C API Functions Contains Session C API Function Argument Data
0x81 System API System C API Functions Contains System C API Function Argument Data
0x82 Query API Query C API Functions Contains Query C API Function Argument Data

Directive Command

A code (one byte) that references a command (or function) that is part of the M2ALP referenced in the ALP ID (part of NDEF ID). The values of the Directive Command are dependent on the individual M2ALPs.

opentag/alpapi.txt · Last modified: 2012/03/01 20:48 by jpnorair