Indigresso Wiki

Open Source Stuff for DASH7

User Tools

Site Tools


opentag:api:alpapi

ALP API (Messaging API)

OpenTag's API model includes a messaging API for communication between client and server. This API typically uses the MPipe as a means of communication, but any pipe/FIFO that can hold an ALP-type wrapper can serve as an API communications pipe (one example here is an OpenTag Queue).

Basic ALP Data Wrapper

DASH7 ALP Main Article
The ALP data wrapper is a truncated version of the NDEF wrapper, so it is easy to convert between ALP and NDEF. OpenTag/DASH7 do not utilize the full NDEF featureset, so some of the fields can be removed. Namely: ALP does not use the SR, IL, or TNF flags in the NDEF flag byte, ALP does not have a Type Length or Type Field, and ALP always has a 2-byte ID. Therefore, the ALP wrapper looks like the following:

ALP Record (Header = 4 bytes)
Record Flags Payload Length ALP ID (ID1) Cmd ID (ID0) Payload
1 Byte 1 Byte 1 Byte 1 Byte N Bytes
(bitfield) N (integer) 0-255 0-127 Data

The most significant bit (b7) of the Command ID is reserved and used by the client to tell the server that it should form a response (which is ALP and command-dependent) and return it to the client when the command has completed.

OTcom & Quickstart Guide

The ALP API is the one that you would use if communicating with an OpenTag device via OTcom (or a similar type of program), and it is the one discussed in the API Quickstart Guide.

Connection to OTAPI (C API)

OTAPI Main Article
OTAPI is OpenTag's function-based API wrapper written in C. It offers a very-slightly-sandboxed interface with some key modules in OTlib. The OpenTag ALP API includes protocols & commands that replicate OTAPI functions, but in a message-based interface rather than a function-based interface. In other words, the OpenTag ALP API commands include an identifier (like a function name), a data payload (like function arguments), and an output format (like function return value) that map exactly to the way OTAPI functions are declared. So, by using the OpenTag ALP API, you are actually doing the exact same thing as calling functions as if you had written firmware in C and compiled it onto the device.

OpenTag ALPs

OpenTag ALPs are unique to OpenTag. They are not defined in the DASH7 Mode 2

Logger

OTlib Logger Article
The ALP ID 0x03 is used for the Logger. Logger command codes are defined based on the output format of the logger, and the Response bit of the Command ID (bit 7) will cause echo. Client-to-server logger ALP packets may be ignored.

Logger ALP Command IDs
Value Description
0x00 Payload is raw binary
0x01 Payload is UTF-8 text
0x02 Payload is Unicode text
0x03 Payload is UTF-8 text formatted as Hex numbers with spaces (e.g. 1A 2B 3C …)
0x04 Payload is a UTF-8 label followed by raw binary
0x05 Payload is a UTF-8 label followed by UTF-8 text
0x06 Payload is a UTF-8 label followed by Unicode text
0x07 Payload is a UTF-8 label followed by UTF-8 Hex numbers

UTF-8 label are space-terminated

Example: Command 07

The UTF-8 Label + Hex number message is a very frequently used logging method for debugging. The OTAPI Logger function that would push this is: (possibly not legal C)

otapi_log_hexmsg(4, 6, "DUMP", {0x1A, 0x2B, 0x3C, 0x4D, 0x5E, 0x6F} );
Example Command 07 Record
Flags Length ALP ID Cmd ID Payload (UTF-8)
0xDD 22 03 07 “DUMP 1A 2B 3C 4D 5E 6F”

Example: Command 00

The raw binary command can be used to push any type of unformatted data. Here is a usage example, similar to the one above:

otapi_log(0, 8, {0x00, 0xFF, 0x11, 0xEE, 0x22, 0xDD, 0x33, 0xCC} );
Example Command 00 Record
Flags Length ALP ID Cmd ID Payload (raw)
0xDD 08 03 00 00FF11EE22DD33CC

Example: Echo

If you are a client and you send either of the above records to an OpenTag server, it will do nothing. However, if you set the Response Bit (b7) – yielding Command IDs 0x87 and 0x80 respectively – it will echo the record back to the client.

Session

OTlib Session Article
OTAPI C-API Article
The ALP ID 0x80 is used for the Session API. Session Command IDs correspond to OTAPI session functions. If the Respond Bit is set, the return value from the corresponding OTAPI function will be returned to the client.

Session ALP Command IDs
Value Associated OTAPI Session Function Description
0x00 Null (no associated function)
0x01 otapi_session_number() returns session number of top session (0 if no session)
0x02 otapi_flush_sessions() returns number of sessions in the stack, after flush
0x03 otapi_is_session_blocked(ch_id) returns true/false if supplied channel ID has a scheduled session

Session Number and Flush Commands

The first two commands (Session Number and Flush) have no arguments, therefore no ALP payload is 0 bytes. The resultant ALP record will look like the example below.

Example Command 01, 02
Flags Length ALP ID Cmd ID Payload
0xDD 0 0x80 01/02

Is Session Blocked Command

The “is session blocked” command has a single, 1-byte argument that is used in the record payload. This argument is the Channel ID that is being checked for blocking.

Example Command 03
Flags Length ALP ID Cmd ID Payload (Chan 0x12)
0xDD 1 0x80 03 0x12

System

OTlib system.h Article
OTAPI C-API Article
The ALP ID 0x81 is used for the System API. The system API deals with setup and MAC-layer tasks. In form and function, there is some overlap between the Session API and the System API, to the point that the Session API is mostly a bonus. The System API, however, needs to be used in order to create a dialog (and, incidentally, a session).

Session ALP Command IDs
Value Associated OTAPI Function Description
0x00 Null (no associated function)
0x01 otapi_sysinit() returns session number of top session (0 if no session)
0x02 otapi_new_session(session_tmpl*) returns new session number
0x03 otapi_open_request(ot_u8, routing_tmpl*) returns length of TX Queue as function returns
0x04 otapi_close_request() finishes request, returns final TX Queue length
0x05 otapi_start_flood(ot_u16) returns true/false if flood has been initialized (or not)
0x06 otapi_start_dialog() returns true/false if request has been initialized (or not)

Transport (M2QP)

OTlib M2QP Article
OTAPI C-API Article
The ALP ID 0x82 is used for the M2QP/Transport API. Each M2QP ALP command corresponds to an OTAPI M2QP function, and each function builds one of the data templates used in DASH7 M2QP. The M2QP API is very low level, and it requires some understanding of the DASH7 specification and how M2QP forms command requests. ALP record examples will not be listed for M2QP, because the structure should be apparent from the Logger, Session, and System sections. However, a list of the command templates is provided.

Value Associated OTAPI Function Description
0x00 Null (no associated function)
0x01 otapi_put_command_tmpl(ot_u8*, command_tmpl*) returns status (1 byte) and length of TX Queue (2 bytes)
0x02 otapi_put_dialog_tmpl(ot_u8*, dialog_tmpl*)
0x03 otapi_put_query_tmpl(ot_u8*, query_tmpl*)
0x04 otapi_put_ack_tmpl(ot_u8*, ack_tmpl*)
0x05 otapi_put_error_tmpl(ot_u8*, error_tmpl*)
0x06 otapi_put_isf_comp(ot_u8*, isfcomp_tmpl*)
0x07 otapi_put_isf_call(ot_u8*, isfcall_tmpl*)
0x08 otapi_put_isf_return(ot_u8*, isfcall_tmpl*)
0x09 otapi_put_reqds(ot_u8*, Queue*)
0x0A otapi_put_propds(ot_u8*, Queue*)
0x0B otapi_put_shell_tmpl(ot_u8*, shell_tmpl*)

Call Order

The M2QP ALP API is very low-level to the point that it is not really abstracted at all. The functions must be called in the order that they appear in the M2QP spec. This order is: (1) otapi_put_command_tmpl, (2) otapi_put_dialog_tmpl, (3) one or more of the remaining template functions. M2QP API's can be wrapped into other API's, in order to create abstracted, application-specific APIs.

M2QP API Templates

The M2QP API follows the OTAPI Common Form, so each M2QP OTAPI function takes a template pointer as an argument, and each M2QP ALP call must contain this template data (which gets stored temporarily while the OTAPI function runs). These templates are defined in OTlib/OT_tmpl.h, apart from the Queue data type which is defined in the Queue Module.

Template Usage Data Elements
command_tmpl Command Specification ot_u8 type ot_u8 opcode ot_u8 extension
NA2P/ERR/A2P cmd opcode cmd extension
dialog_tmpl Response Window Spec ot_u16 timeout ot_u16 channels ot_u8* chanlist
timeout ticks 0-8 resp chans resp chan list
query_tmpl Query generation ot_u8 code ot_u8 length ot_u8* mask ot_u8* value
M2QP query code token length token mask (opt) token value (opt)
ack_tmpl A2P Multicast ACKing ot_u8 count ot_u8 length ot_u8* list
# of ACKs 2 or 8 bytes/ID ACK stream
error_tmpl Error Specification ot_u8 code ot_u8 subcode ot_u8* data
M2QP error definition
isfcomp_tmpl ISF Query Data ot_u8 is_series ot_u8 isf_id ot_s16 offset
T/F on use ISFS file/series ID offset into file
isfcall_tmpl ISF Return Data ot_u8 is_series ot_u8 isf_id ot_s16 max_return ot_s16 offset
T/F on use ISFS file/series ID max bytes to return offset into file
shell_tmpl UDP Payload ot_u8 req_port ot_u8 resp_port ot_u8 data_length ot_u8* data
Port: 0-255 Port: 0-255 payload length payload

Note: when a string/stream is required (ot_u8*), the string must be included in full into the ALP message. The length of the string is usually defined directly in a preceding data element, but other times (query_tmpl, error_tmpl) the length is defined in part of a preceding data element (query_code, subcode). Check the DASH7 Mode 2 Spec for more information.

DASH7 Standardized ALPs

The DASH7 specification defines ALPs for File Data Access, Sensor Access, and Security Exchange. These are implemented in OpenTag according to the DASH7 spec, and the spec should be referred to for complete information on these.

opentag/api/alpapi.txt · Last modified: 2012/03/29 09:44 by jpnorair