Indigresso Wiki

Open Source Stuff for DASH7

User Tools

Site Tools


opentag:otlib:alp

ALP (OTlib)

“ALP” stands for Application Layer Protocol, although that term is somewhat generic, so in OpenTag and DASH7 Mode 2 it is most commonly referred-to simply as “ALP” or “M2ALP.” The ALP format is a simple data wrapper, based on NDEF, and its main feature is support for data fragmentation. ALP does not have extensive data structuring, so data or command-oriented protocols can be embedded inside the ALP wrapper to give them a common fragmentation and identification method that is supported by DASH7 Mode 2 (and OpenTag).

ALP Handling

ALP communication can be managed over different interfaces, but the OpenTag code that processes the ALP frames is universal apart from the communication interface driver itself.

OTlib Code Files used in ALP Handling

Officially supported ALP handling code is part of OTlib. Unofficial or experimental ALP handlers are stored in OTlibext, and proprietary ALPs should be stored with the application that uses them.

  • ALP Module
    • alp.h: main ALP header file
    • alp_main.c: main ALP parser for servers – vectors ALPs to embedded protocol parsers
    • alp_….c: protocol parsers for command/data protocols embedded as ALPs
  • NDEF Module
    • ndef.h: NDEF module header file (used by MPipe)
    • ndef.c: NDEF parser functions
  • OTAPI Headers
  • Other Relevant OTlib Modules

ALPs over MPipe

MPipe is a very simple PHY/MAC, with no inherent addressing, that is intended to serve as a point-to-point connection between a client and a server. Usually it is implemented on some sort of wireline PHY, such as UART, SPI, USB-CDC, etc. ALPs can be transferred over MPipe by using the NDEF Normal Form.

ALPs over DASH7

The DASH7 Datastream Commands in M2QP can be used to push ALPs over a DASH7 network. Small ALP data can be pushed in a single datastream command frame, and larger ALP data can be negotiated via the M2QP datastream method and transferred in a point-to-point M2DP stream (this is all part of the DASH7 Mode 2 spec). TCP/IP-type or UDP/IP-type streams can be handled over DASH7 using ALPs in this method.

ALPs over Queues

Any queue defined by the Queue module) can be used to store an ALP and push it to the ALP handler. In this way, an ALP can be formed by a process running on a server that enables API features to be sent to the kernel running on the same server. The process is quite similar to interprocess communication in POSIX, although much lighter-weight.

OTlib/alp.h

The code from alp.h is pasted below, although you can also check the doxygen code documentation.

#include "OT_types.h"
#include "OT_config.h"
#include "OTAPI_tmpl.h"
#include "queue.h"

/** ALP Record Header
  * ALP Records can be used for NDEF and LLDP.  LLDP is basically just a reduced
  * version of NDEF that satisfies the minimum needs of ALP.  For NDEF, certain
  * data is assumed and/or thrown away.
  */
  
#define ALP_FLAG_MB     0x80    // Message Start bit
#define ALP_FLAG_ME     0x40    // Message End bit
#define ALP_FLAG_CF     0x20    // Chunk Flag
  
typedef struct {
    ot_u8       flags;              // just message end and chunk flag flags
    ot_u8       payload_length;
    ot_u8       dir_id;
    ot_u8       dir_cmd;
    void*       bookmark;           // Internal use only (private)
} alp_record;


#if ((OT_FEATURE(SERVER) == ENABLED) && (OT_FEATURE(ALP) == ENABLED))

/** @note User IDs for ALP's
  * Most ALP commands require some form of user authentication to run.  This is
  * analagous for a user having to log-in to a POSIX shell in order to run the
  * applications on the system.  The User ID needs to be authenticated to a 
  * device ID via the auth system if the ALP's are being transmitted over the 
  * air (via DASH7).
  */


/** @brief  Process a received ALP record (vectors to all supported ALP's)
  * @param  in_rec      (alp_record*) Header of input ALP record, to be processed
  * @param  out_rec     (alp_record*) Header of output ALP record, due to processing
  * @param  in_q        (Queue*) input queue containing record
  * @param  out_q       (Queue*) output queue for [optional] record response
  * @param  user_id     (id_tmpl*) user id for performing the record 
  * @retval None
  * @ingroup ALP
  *
  * ID values (from spec)
  * 0x00:       Null subprotocol
  * 0x01:       Filesystem subprotocol
  * 0x02:       Sensor Configuration subprotocol (pending)
  * 0x11-14:    Security subprotocols (pending)
  */
void alp_proc(alp_record* in_rec, alp_record* out_rec, Queue* in_q, Queue* out_q, id_tmpl* user_id);


/** @note Subprotocol processing functions
  * The functions below are exposed, but they never should be called unless you
  * are writing some sort of hack or optimized version.  Instead, call the
  * alp_proc() function with the ID parameter set appropriately.
  */

/** @brief  Process a received filesystem ALP record
  * @param  in_rec      (alp_record*) Header of input ALP record, to be processed
  * @param  out_rec     (alp_record*) Header of output ALP record, due to processing
  * @param  in_q        (Queue*) input queue containing record
  * @param  out_q       (Queue*) output queue for [optional] record response
  * @param  user_id     (id_tmpl*) user id for performing the record 
  * @retval None
  * @ingroup ALP
  */
void alp_proc_filedata(alp_record* in_rec, alp_record* out_rec, Queue* in_q, Queue* out_q, id_tmpl* user_id);


#if (OT_FEATURE(SENSORS) == ENABLED)
/* @brief  Process a received sensor configurator ALP record (not implemented)
  * @param  in_rec      (alp_record*) Header of input ALP record, to be processed
  * @param  out_rec     (alp_record*) Header of output ALP record, due to processing
  * @param  in_q        (Queue*) input queue containing record
  * @param  out_q       (Queue*) output queue for [optional] record response
  * @param  user_id     (id_tmpl*) user id for performing the record 
  * @retval None
  * @ingroup ALP
  */
void alp_proc_sensor(alp_record* in_rec, alp_record* out_rec, Queue* in_q, Queue* out_q, id_tmpl* user_id);
#endif


#if (OT_FEATURE(DASHFORTH) == ENABLED)
#   if (OT_FEATURE(CAPI) != ENABLED)
#       error For DASHForth to work, C-API must be ENABLED (it is not: check OT_config.h).
#   endif
/** @brief  Process a received DASHFORTH ALP record
  * @param  in_rec      (alp_record*) Header of input ALP record, to be processed
  * @param  out_rec     (alp_record*) Header of output ALP record, due to processing
  * @param  in_q        (Queue*) input queue containing record
  * @param  out_q       (Queue*) output queue for [optional] record response
  * @param  user_id     (id_tmpl*) user id for performing the record 
  * @retval None
  * @ingroup ALP
  */
void alp_proc_dashforth(alp_record* in_rec, alp_record* out_rec, Queue* in_q, Queue* out_q, id_tmpl* user_id);
#endif


#if (LOG_FEATURE(ANY) == ENABLED)
/** @brief  Process a received logger ALP record (typically client only)
  * @param  in_rec      (alp_record*) Header of input ALP record, to be processed
  * @param  out_rec     (alp_record*) Header of output ALP record, due to processing
  * @param  in_q        (Queue*) input queue containing record
  * @param  out_q       (Queue*) output queue for [optional] record response
  * @param  user_id     (id_tmpl*) user id for performing the record 
  * @retval None
  * @ingroup ALP
  */
void alp_proc_logger(alp_record* in_rec, alp_record* out_rec, Queue* in_q, Queue* out_q, id_tmpl* user_id);
#endif


#if (OT_FEATURE(ALPAPI) == ENABLED)
#   if (OT_FEATURE(CAPI) != ENABLED)
#       error For ALP-API to work, C-API must be ENABLED (it is not: check OT_config.h).
#   endif
/** @brief  Process a received Session API record
  * @param  in_rec      (alp_record*) Header of input ALP record, to be processed
  * @param  out_rec     (alp_record*) Header of output ALP record, due to processing
  * @param  in_q        (Queue*) input queue containing record
  * @param  out_q       (Queue*) output queue for [optional] record response
  * @param  user_id     (id_tmpl*) user id for performing the record 
  * @retval None
  * @ingroup ALP
  */
void alp_proc_api_session(alp_record* in_rec, alp_record* out_rec, Queue* in_q, Queue* out_q, id_tmpl* user_id);


/** @brief  Process a received System API record
  * @param  in_rec      (alp_record*) Header of input ALP record, to be processed
  * @param  out_rec     (alp_record*) Header of output ALP record, due to processing
  * @param  in_q        (Queue*) input queue containing record
  * @param  out_q       (Queue*) output queue for [optional] record response
  * @param  user_id     (id_tmpl*) user id for performing the record 
  * @retval None
  * @ingroup ALP
  */
void alp_proc_api_system(alp_record* in_rec, alp_record* out_rec, Queue* in_q, Queue* out_q, id_tmpl* user_id);


/** @brief  Process a received Query API record
  * @param  in_rec      (alp_record*) Header of input ALP record, to be processed
  * @param  out_rec     (alp_record*) Header of output ALP record, due to processing
  * @param  in_q        (Queue*) input queue containing record
  * @param  out_q       (Queue*) output queue for [optional] record response
  * @param  user_id     (id_tmpl*) user id for performing the record 
  * @retval None
  * @ingroup ALP
  */
void alp_proc_api_query(alp_record* in_rec, alp_record* out_rec, Queue* in_q, Queue* out_q, id_tmpl* user_id);
#endif


#if (OT_FEATURE(SECURITY) == ENABLED)
/** @brief  Process a received Security/Auth ALP record (not implemented)
  * @param  in_rec      (alp_record*) Header of input ALP record, to be processed
  * @param  out_rec     (alp_record*) Header of output ALP record, due to processing
  * @param  in_q        (Queue*) input queue containing record
  * @param  out_q       (Queue*) output queue for [optional] record response
  * @param  user_id     (id_tmpl*) user id for performing the record 
  * @retval None
  * @ingroup ALP
  */
void alp_proc_sec_example(alp_record* in_rec, alp_record* out_rec, Queue* in_q, Queue* out_q, id_tmpl* user_id);
#endif
opentag/otlib/alp.txt · Last modified: 2012/03/28 15:08 by jpnorair