Indigresso Wiki

Open Source Stuff for DASH7

User Tools

Site Tools


opentag:configuration

OpenTag Configuration

OpenTag can be configured for many different types of device/host behavior. There are two kinds of configuration: compile-time configuration and runtime configuration.

Runtime Configuration

The runtime configuration is managed via the OpenTag/DASH7 Registry, which is held in the lower part of the ISF Veelite filesystem. All compliant DASH7 devices must have these ISF files implemented. The runtime configuration files can be read, written, or modified during runtime by the APIs or the filesystem ALP. These files must be supplied with default data, also, which is supplied at compile-time or linking-time (for simplicity, we will consider that linking-time is the same as compile-time).

Compile Time Configuration

The compile-time configuration is managed through several configuration headers (.h files) and may be extended to GNU automake (or similar) build models. Compile-time configuration also requires default data to be written to the DASH7 Registry. These default data are generally stored in a .c file kept with the application code files (e.g. /Apps/Demo_PingPong/Code/data.c). The data file is filled with const char arrays that are mapped to areas of memory defined in the .h configuration headers.

Using Runtime Configuration Methods

Runtime configuration methods require usage of the Filesytem API or ALP (the Filesystem API is ancillary to the OpenTag API). Configuration files have the following properties:

  • They have file permissions just like any other file.
  • They are stored in the ISF files, IDs 0-15 (0x00 - 0x0F)
  • They can be read or written, pursuant to their file permissions, but cannot be deleted (even by root).

API Usage Example

Runtime configuration files are normal files, and the user can access them just the same. Access of files over the API is limited to the C-API, however, there is a special ALP for filesystem access that allows usage of MPipe or DASH7 (see below).

#include "OT_config.h"
#include "OT_types.h"
#include "veelite.h"

ot_bool modify_UID(ot_u8* new_uid) {
    vlFILE* fp;
    
    // Open the "Device Features" ISF file, which contains the 8 byte UID.
    // The "NULL" is a specifier for the Root user.  Usage of "NULL" should is
    // only available to the API.  The ALP enforces user authentication.
    vl_open(fp, ISF_ID(device_features), NULL);
    
    // You could remove this check, because the configuration files will always
    // be present on the device.  It is just here for example purposes.
    if (fp == NULL) return False;
    
    // Writes (and reads) to the filesystem are most efficient when done through 
    // 16 bit halfwords.  The second argument is the write offset (the UID is in
    // the first 8 bytes of this file).  To write an odd number of bytes, use an
    // odd offset and assure the write-data is in the upper half of the input.
    vl_write(fp, 0, ((ot_u16*)new_uid)[0]);
    vl_write(fp, 2, ((ot_u16*)new_uid)[1]);
    vl_write(fp, 4, ((ot_u16*)new_uid)[2]);
    vl_write(fp, 6, ((ot_u16*)new_uid)[3]);
    
    // Close the file (This is important!)
    vl_close(fp);
    
    return True;
}

ALP Usage

Filesystem access is highly guarded (for security reasons), so filesystem API access is not available over the MPipe as it could be a security risk. However, there is a separate filedata ALP that allows interfacing with the filesystem over a message-based interface (this can be MPipe, DASH7, or basically anything). The DASH7 Mode 2 specification defines this filedata ALP. The OpenTag implementation is in /OTlib/alp_filedata.c.

Configuring Compile-time Settings

Registry Default Source Files

Compile-time Registry defaults are primarily set in two source files.

  • The Application Configuration File (/Apps/APP_NAME/Code/app_config_APP_NAME.h) stores the default file header attributes. This includes default file allocations, lengths, and other header information.
  • Some file in the Application Code folder (/Apps/APP_NAME/Code) needs to contain the actual data that gets put into the Registry at compile-time. This is usually main.c or data.c, but it can be anything.

Rules for Feature Configuration

In the OpenTag codebase, preprocessor references can be made (e.g. #if (FEATURE(SUB_FEATURE) == ENABLED)), thereby allowing a single codebase to be compiled in different ways, and to stay optimized for all cases. Many features are defined simply as a matter of enabling or disabling. In these cases, they are defined as ENABLED or DISABLED or in certain cases NOT_AVAILABLE (which is identical to DISABLED).

Source Files with Feature Configuration

The Application Configuration file defines the way OpenTag and DASH7 are configured, allowing the OTlib source to be compiled optimally. The Platform Configuration file defines what features are available to the Platform, allowing the Platform source to be compiled optimally.

  • Application Configuration: /Apps/APP_NAME/Code/app_config_APP_NAME.h
  • Platform Configuration: /Platforms/PLATFORM_NAME/Code/platform_config_PLATFORM_NAME.h
FEATURE Notation

In configuration headers, a very common notation is shown below:

#define XX_FEATURE(VAL)         XX_FEATURE_##VAL
#define XX_FEATURE_EXAMPLE1     ENABLED
#define XX_FEATURE_EXAMPLE2     DISABLED

When comparing features in code (C files), always use the Macro notation, i.e. XX_FEATURE(EXAMPLE1). This allows undefined features to resolve to 0 (DISABLED). Also, always compare against ENABLED, not DISABLED. The C preprocessor can use implicit referencing, so using #if (XX_FEATURE(EXAMPLE1) != ENABLED) is safer than using #if (XX_FEATURE(EXAMPLE1) == DISABLED).

PARAM Notation

Some other features are defined as an integer or enumerated value. In these cases, the value is often an amount of memory allocated to supporting a feature. The Notation is identical to the FEATURE Notation except that the defined value can be more than just ENABLED, DISABLED, or NOT_AVAILABLE. The notation is:

#define XX_PARAM(VAL)           XX_PARAM_##VAL
#define XX_PARAM_EXAMPLE1       6
#define XX_PARAM_EXAMPLE2       15.259

Application Configuration

The header file /Apps/APP_NAME/Code/app_config_APP_NAME.h is included in almost every file in OpenTag, indirectly via /Apps/APP_NAME/Code/build_config.h, which itself is included in /OTlib/OT_config.h. As a result, /OTlib/OT_config.h is the file that should be included in all OpenTag source files, in order to provide configuration settings for the following features:

  • OpenTag Core featureset allocation
  • Automated Logging Configuration
  • DASH7 Mode 2 featureset allocation
  • DASH7 Mode 1 featureset allocation (currently not supported)
  • File memory configuration
  • Filesystem configuration
    • Generic File Block (GFB) allocation and addressing
    • Indexed Short File Series (ISFS) allocation and addressing
    • Indexed File Series (ISF) allocation and addressing
    • Filesystem Mirroring configuration

OpenTag Core Featureset Allocation

OpenTag core featureset allocations are available to C programmers who include OT_config.h (the actual configuration is done in /Apps/APP_NAME/Code/app_config_APP_NAME.h, which gets included into OT_config.h). Each feature is defined using the Rules for Feature Notation.

OpenTag core features can be referenced via the C preprocessor by the following notation:
OT_FEATURE(FEATURE_NAME)

Allowing Non-Standard Features

Non-standard (unofficial) features can be added to the OpenTag Core Featureset list, although care must be taken when using them in code to make sure that they are ignored when not defined (as in, when unofficial code is compiled with a configuration file from an official build). In your local source files that utilize the unofficial features, you should make a wrapper constant that takes on 0/DISABLED when the Feature is not defined. Here is an example:

#ifdef OT_FEATURE(NONSTANDARD_EXAMPLE)
#   define LOCAL_NONSTANDARD_EXAMPLE    OT_FEATURE(NONSTANDARD_EXAMPLE)
#else
#   define LOCAL_NONSTANDARD_EXAMPLE    DISABLED
#endif

// Now you can use LOCAL_NONSTANDARD_EXAMPLE in your unofficial source code without worry

Standard Core Feature Definitions

Below is the complete list of OpenTag Core Feature definitions, as of the time of writing (25 Jan 2012). Features written in BOLD text are also noted in the Firmware Version data element of the Device Features ISF.

FEATURE_NAME Description
SERVER “Server” is a build containing the OpenTag stack
CLIENT “Client” is a command console (typ. PC)
CAPI “otapi” C function usage in server-side apps
DASHFORTH DASHFORTH Applet VM (server-side), or JIT (client-side)
LOGGER Data logging & TTY via OTAPI logger submodule
ALP Application Layer Protocol Support (always ENABLED on Client builds)
ALPAPI Application Layer Protocol callable messaging API's
MPIPE MPipe messaging interface
NDEF NDEF data wrapping (needed with ALP or MPipe)
VEELITE OpenTag/DASH7 File System
VLNVWRITE Allows Non-volatile (flash) file writing in Veelite
VLNEW Allows file create/delete in Veelite
VLRESTORE Allows file restoring in Veelite (this requires extra flash to backup files)
VL_SECURITY Allows files to be encrypted while stored in the Filesystem
DLL_SECURITY AES128 encryption with pre-shared keys, implemented at Data-Link-Layer
NL_SECURITY Network Layer Security using IKEv2/IPsec + DASH7 NLS Spec
SENSORS DASH7-based spec for sensor interfacing
LF Optional LF side-channel interface (~125 kHz)
HF Optional HF side-channel interface (~13.56 MHz)
AUTOCOPY “platform_memcpy” is implemented using DMA HW
CRC_TXSTREAM Streaming CRC for TX: must be ENABLED (deprecated)
CRC_RXSTREAM Streaming CRC for RX: must be ENABLED (deprecated)
RTC A high-precision Real-Time Clock crystal is implemented
M1 Mode 1 Featureset: must be DISABLED
M2 Mode 2 Featureset: must be ENABLED
SYSKERN_CALLBACKS Application callbacks from System kernel events
SYSRF_CALLBACKS Application callbacks from System radio driver events
SYSIDLE_CALLBACKS Application callbacks from System idle-time events
M2NP_CALLBACKS Application callbacks from Network Layer events (frame routing)
M2QP_CALLBACKS Application callbacks from Transport Layer events (dialog processing)
MPIPE_CALLBACKS Application callbacks from Mpipe driver events
SW_WATCHDOG System/Kernel task watchdog is implemented in software
HW_WATCHDOG System/Kernel task watchdog is implemented using HW watchdog timer

Standard Core Parameters

PARAM_NAME Type Range Description
VLFPS Integer 2-255 Number of Veelite Files able to be open simultaneously
SESSION_DEPTH Integer 1-255 Number of Sessions the device can queue/schedule simultaneously
BUFFER_SIZE Integer 256+ Bytes of RAM allocated to OpenTag buffers: typically, 512 for basic endpoints, 1024+ for Gateways & devices that support ALP
WATCHDOG_PERIOD Integer 1-1024 Number of ticks before exception occurs, following the expected return-time of a radio driver task

Automated Logging Configuration

Automated logging can be configured for certain, basic events. When these events occur, they will be logged if the corresponding feature is enabled. Other types of OpenTag logging or reporting can still occur through the callbacks, which are features defined in the OpenTag Core Featureset (above).

As with the OpenTag Core Features, Automated Logging feature configuration settings are available to C programmers who include OT_config.h. Each feature is defined as a constant, and usable as a macro (this way some group automation can be integrated). All logging features will be disabled if OT_FEATURE(LOGGER) is set to DISABLED.

At the time of writing (25 Jan 2012), the following features are available for automated logging. The form for usage in preprocessor code is:
LOG_FEATURE(FEATURE_NAME)

FEATURE_NAME Log Label Log Payload Description
FAULTS OT_SKP File Index (2B) + Line (2B) Log FW/HW Errors (System Kernel Panicks)
FAILS OT_PTE Stack Pointer Traceback Log Watchdog Exceptions (Process Timeout Errors)
RESPONSES OT_RSP M2QP Response frame data Log Qualified M2QP Responses
ANY N/A N/A Logical OR of all settings above

DASH7 Mode 2 featureset allocation

Mode 2 featureset configuration settings are available to C programmers who include OT_config.h. Each feature is defined as a constant, and usable as a macro (this way some group automation can be integrated). The form is: M2_FEATURE(VAL)

Currently, the following features are available:

VAL Type Description
M2DP Enable/Disable Datastreams & associated commands
GATEWAY Enable/Disable Gateway device mode
SUBCONTROLLER Enable/Disable Subcontroller device mode
ENDPOINT Enable/Disable Endpoint device mode
BLINKER Enable/Disable Blinker device mode
BASE Enable/Disable Base channels (ch 00, 80)
LEGACY Enable/Disable Legacy (Mode 1) channel (ch 01)
NORMAL Enable/Disable Low-speed channels (ch 1x, 9x)
TURBO Enable/Disable High-speed channels (ch 2x, Ax)
BLINK Enable/Disable Blink channels (ch 3x, Bx)
FECTX Enable/Disable FEC support for transmissions
FECRX Enable/Disable FEC support for receptions
AUTOSCALE Enable/Disable Adaptive TX power fall-off algorithm
BEACONS Enable/Disable Automated Beacon transmissions
MI_CHANNELS Number Multi-input channel support, e.g. “MIMO” (1-8)
MAXFRAME Number Max supported frame length in bytes (127-255)
MFPP Number Maximum Frames per Packet (1-255, partly device-dependent)
MULTIFRAME Enable/Disable Derived from MFPP > 1
FEC Enable/Disable Derived from FECTX/FECRX

DASH7 Mode 1 featureset allocation (currently not supported)

Mode 1 featureset configuration settings would be available to C programmers who include OT_config.h, if Mode 1 features were to be implemented (currently they are not). Each feature is defined as a constant, and usable as a macro (this way some group automation can be integrated). The form is: M1_FEATURE(VAL)

File memory configuration

File memory settings are important to configure, because they feed into other OTlib and Platform modules that make use of file memory. C programmers may refer to them in their code, but typically these configuration settings only need to be used by OpenTag modules. The typical form of file memory constants is: OTF_…

Note that many of the settings anticipate usage of Flash memory. If Flash memory is not used, then Flash can either be simulated (as is the case in the simulator) or you can set it up such that only a single “page” is used.

Setting Type Description
OTF_VWORM_PAGES Number Total number of Flash Pages to use for File Memory
OTF_VWORM_FALLOW_PAGES Number Number of Flash Pages to use for “Fallow” Pages
OTF_VWORM_PAGESIZE Number Number of bytes in a flash page (typ from platform_config.h)
OTF_VWORM_WORD_BYTES Number Number of bytes in a flash word (typ from platform_config.h)
OTF_VWORM_WORD_BITS Number Number of bits in a flash word (typ from platform_config.h)
OTF_VWORM_SIZE Derived Number Number of total bytes in the File memory
OTF_VWORM_START_PAGE Number Page number/index of the first page used by File memory
OTF_VWORM_START_ADDR Number Address of the first address used by File Memory
OTF_CRC_TABLE Enable/Disable Enables the usage of CRC lookup table
OTF_UHF_TABLE Enable/Disable Enables the usage of one or more encoding tables for UHF
OTF_UHF_TABLESIZE Number Number of total bytes in UHF Tables (legacy, deprecated)
OTF_M1_ENCODE_TABLE Enable/Disable Enables a UHF table for Mode 1 PHY encoding/decoding
OTF_M2_ENCODE_TABLE Enable/Disable Enables a UHF table for Mode 2 PHY encoding/decoding
OTF_TOTAL_PAGES Derived Number Sum of all Flash pages used for file memory

Additional, derived file memory configuration settings

These settings are part of OT_config.h, but they do not need to be configured at all by the user because they are automatically derived from other configuration settings (such as those above). They are listed below:

  • OTF_TOTAL_SIZE
  • OTF_START_PAGE
  • OTF_START_ADDR
  • OTF_LOOKUP_LAST_PAGE
  • OTF_VWORM_LAST_PAGE
  • OTF_VWORM_END_ADDR

Filesystem configuration

Generic File Block (GFB) allocation and addressing

Generic File Block (GFB) settings are important to configure, because they feed into other OTlib and Platform modules that make use of file memory. C programmers may refer to them in their code, but typically these configuration settings only need to be used by OpenTag modules. The typical form of GFB constants is: GFB_…

Setting Type Description
GFB_TOTAL_BYTES Number Total number of bytes used for GFB files
GFB_START_VADDR Number Starting virtual address of GFB files
GFB_FILE_BYTES Number Number of bytes allocates for GFB files
GFB_NUM_STOCK_FILES Number Number of GFB files included as default, at compile-time
GFB_NUM_USER_FILES Number Number of GFB files reserved for user purposes
GFB_NUM_FILES Derived Number Total number of GFB Files
GFB_MOD_standard Number Standard/Default file permissions byte value for GFB files
GFB_HEAP_BYTES Derived Number Number of total bytes in the GFB Heap

Indexed Short File Series (ISFS) allocation

Indexed Short File Series (ISFS) settings are important to configure, because they feed into other OTlib and Platform modules that make use of file memory. C programmers may refer to them in their code, but typically these configuration settings only need to be used by OpenTag modules. The typical form of ISFS constants is: ISFS_…

Setting Type Description
ISFS_TOTAL_BYTES Number Total Bytes available to the ISFS Block
ISFS_START_VADDR Number Start Virtual address for ISFS Files
ISFS_NUM_M1_LISTS Number Number of stock ISFS Files (called lists here) reserved for Mode 1 and Mode 2 usage
ISFS_NUM_M2_LISTS Number
ISFS_NUM_EXT_LISTS Number Number of non-stock ISFS Files (called lists here) available to users
ISFS_NUM_USER_LISTS Derived Number Same as ISFS_NUM_EXT_LISTS
ISFS_NUM_STOCK_LISTS Derived Number Number of ISFS Files (called lists here) used by M1 & M2
ISFS_NUM_LISTS Derived Number Total number of available ISFS Files (called Lists here)
ISFS_STOCK_HEAP_BYTES Derived Number Bytes allocated to ISFS Stock files
ISFS_HEAP_BYTES Derived Number Total Bytes allocated to ISFS Block (sometimes identical to ISFS_TOTAL_BYTES)

Indexed Short File Series (ISFS) addressing

The ISFS also contains a set of macros that are usable by C programmers who are writing apps that access the files. The macros take the forms shown below, and include one for each ISFS file available to the OpenTag compilation. If you are adding new stock files to OpenTag compilations, you should add new file constant references to the list in OT_config.h.
ISFS_ID(VAL) → Returns ISFS file ID of VAL reference
ISFS_MOD(VAL) → Returns ISFS file permissions value of VAL reference
ISFS_LEN(VAL) → Returns ISFS file length of VAL reference
ISFS_MAX(VAL) → Returns ISFS max file length of VAL reference
ISFS_ALLOC(VAL) → Returns ISFS file allocation of VAL reference
ISFS_BASE(VAL) → Returns ISFS Base virtual address of VAL reference

Stock (VAL) File References Notes
transit_data Mode 1 & Mode 2
capability_data Mode 1 & Mode 2
query_results Mode 1 & Mode 2
hardware_fault Mode 1 & Mode 2
device_discovery Mode 2
device_capability Mode 2
device_channel_utilization Mode 2
location_data Mode 2

Indexed Short File (ISF) allocation

Indexed Short File (ISF) settings are important to configure, because they feed into other OTlib and Platform modules that make use of file memory. C programmers may refer to them in their code, but typically these configuration settings only need to be used by OpenTag modules. The typical form of ISFS constants is: ISF_…

Setting Type Description
ISF_TOTAL_BYTES Number Total Bytes available to the ISF Block
ISF_START_VADDR Number Start Virtual address for ISF Files
ISF_MIRROR_VADDR Number Start Virtual address of the ISF Mirror (if a mirror is available)
ISF_NUM_M1_FILES Number Number of stock ISF Files reserved for Mode 1 and Mode 2 usage
ISF_NUM_M2_FILES Number Number of stock ISF Files reserved for Mode 2 usage
ISF_NUM_STOCK_FILES Derived Number Number of total stock files (Mode 1 + Mode 2)
ISF_NUM_USER_FILES Number Max number of ISF files that the user may create, in addition to the stock files
ISF_NUM_FILES Derived Number Max number of stock and user files

Indexed Short File (ISF) addressing

The ISF also contains a set of macros that are usable by C programmers who are writing apps that access the files. The macros take the forms shown below, and include one for each ISFS file available to the OpenTag compilation. If you are adding new stock files to OpenTag compilations, you should add new file constant references to the list in OT_config.h.
ISF_ID(VAL) → Returns ISF file ID of VAL reference
ISF_MOD(VAL) → Returns ISF file permissions value of VAL reference
ISF_LEN(VAL) → Returns ISF file length of VAL reference
ISF_MAX(VAL) → Returns ISF max file length of VAL reference
ISF_ALLOC(VAL) → Returns ISF file allocation of VAL reference
ISF_BASE(VAL) → Returns ISF Base virtual address of VAL reference
ISF_MIRROR(VAL) → Returns ISF Mirror virtual address of VAL reference

Stock (VAL) File References Notes
network_settings Mode 2
device_features Mode 2
channel_configuration Mode 2
real_time_scheduler Mode 2
sleep_scan_sequence Mode 2
hold_scan_sequence Mode 2
beacon_transmit_sequence Mode 2
protocol_list Mode 2
isfs_list Mode 2
gfb_file_list Mode 2
location_data_list Mode 2
ipv6_addresses Mode 2
sensor_list Mode 2
sensor_alarms Mode 2
root_authentication_key Mode 2
user_authentication_key Mode 2
routing_code Mode 1 & Mode 2
user_id Mode 1 & Mode 2
optional_command_list Mode 1 & Mode 2
memory_size Mode 1 & Mode 2
table_query_size Mode 1 & Mode 2
table_query_results Mode 1 & Mode 2
hardware_fault_status Mode 1 & Mode 2
external_events_list Mode 1 & Mode 2
external_events_alarm_list Mode 1 & Mode 2
application_extension Mode 1 & Mode 2

ISF Mirroring configuration

Mirroring is an optional feature for ISF files (Indexed Short Files). In systems with Flash memory, it can be an advantage to store frequently written ISF's in an SRAM Mirror (this is because Flash is not efficient to write, and it requires wear-leveling).

ISF files need to be specified in OT_config.h as mirrored files and they need to be granted mirror addresses in their respective veelite file headers. ISF veelite headers are written at the time of file creation or at the time of firmware download in the case of file defaults.

Working with Default Veelite File Headers

Placeholder

Configuring Compile-time Settings in platform_config.h

platform_config.h is included in files that need to know about platform parameters, but not necessarily platform functions. platform_config.h references and includes the accurate platform configuration header that is stored in /Platforms/[platform_name] based on one line at the top of the file:
#define PLATFORM [platform_name]

In this case “[platform_name]” is replaced with one of the supported platforms defined in /OTlib/platform_support.h

opentag/configuration.txt · Last modified: 2012/01/25 23:31 by jpnorair