props.h

Open DMT Client C Source code

// ----------------------------------------------------------------------------
// Copyright 2006-2007, Martin D. Flynn
// All rights reserved
// ----------------------------------------------------------------------------
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// 
// http://www.apache.org/licenses/LICENSE-2.0
// 
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
// ----------------------------------------------------------------------------
// Description:
//  Property definitions
// ---
// Change History:
//  2006/01/04  Martin D. Flynn
//     -Initial release
//  2006/01/17  Martin D. Flynn
//     -Added PROP_GEOF_ARRIVE_DELAY/PROP_GEOF_DEPART_DELAY properties
//     -Renamed PROP_GEOF_VIOLATION to PROP_GEOF_VIOLATION_INTRVL
//     -Renamed PROP_MOTION_DORMANT to PROP_MOTION_DORMANT_INTRVL
//     -Renamed PROP_ODOMETER_# to PROP_ODOMETER_#_VALUE
//  2006/02/13  Martin D. Flynn
//     -Added PROP_MOTION_STOP_TYPE property.
//  2006/05/07  Martin D. Flynn
//     -Added PROP_CMD_GEOF_ADMIN property.
//     -Added PROP_GEOF_VERSION property.
//     -Added PROP_GEOF_COUNT property.
//     -GeoCorr property types renamed to PROP_GEOC_...
//     -Relocated PROP_GEOC_ACTIVE_ID property key (was 0xF561)
//     -Relocated PROP_GEOC_VIOLATION_INTRVL property key (was 0xF571)
//     -Relocated PROP_GEOC_VIOLATION_COUNT property key (was 0xF572)
//  2007/01/28  Martin D. Flynn
//     -Changes to facilitate WindowsCE port
//     -Relocated PROP_CFG_GPS_MODEL from 0xEF22 to 0xEF2A.  This was done to
//      allow other serial port configurations for 0xEFX2 through 0xEFX9.
//     -Relocated PROP_COMM_APN_SETTINGS from 0xF3AA to 0xF3AC
//     -Relocated PROP_GEOC_ACTIVE_ID (again) property key (was 0xF571)
//     -Added the following properties:
//      PROP_CFG_XPORT_BPS, PROP_CFG_GPS_BPS,
//      PROP_GPS_CLOCK_DELTA, PROP_CFG_SERIAL0_BPS, PROP_CFG_SERIAL1_BPS,
//      PROP_COMM_CONNECTION, PROP_COMM_APN_PHONE, PROP_CMD_AUTHORIZE,
//      PROP_STATE_USER_ID and PROP_STATE_USER_TIME, PROP_TEMP_SAMPLE_INTRVL,
//      PROP_TEMP_REPORT_INTRVL, PROP_CMD_SAVE_PROPS, PROP_CMD_RESET,
//      PROP_STATE_DEV_DIAGNOSTIC, PROP_COMM_MIN_SIGNAL, PROP_INPUT_CONFIG_#,
//      PROP_INPUT_STATE, PROP_OUTPUT_CONFIG_#, PROP_ELAPSED_#_VALUE, 
//      PROP_UNDERVOLTAGE_LIMIT, PROP_COMM_ACCESS_PIN, PROP_CFG_SERIAL2_PORT,
//      PROP_CFG_SERIAL2_BPS, PROP_CFG_SERIAL2_DEBUG, PROP_CMD_GEOC_ADMIN, 
//      PROP_MOTION_MOVING_INTRVL, PROP_CFG_SERIAL3_PORT, PROP_CFG_SERIAL3_BPS, 
//      PROP_CFG_SERIAL3_DEBUG
//     -The odometer unit of measurement has changed from 0.1 meter to 1 meter
//      units for the following properties:
//          PROP_GPS_ACCURACY, PROP_GPS_DISTANCE_DELTA, 
//          PROP_ODOMETER_#_VALUE, PROP_ODOMETER_#_LIMIT
//      A 0.1 meter resolution did not provide a high enough top end value that
//      could be represented in 4 bytes.  The change to 1 meter units provides a
//      maximum odometers value increase from about 267K miles (which many vehicles
//      have been able to attain) to about 2.67M miles (we'll beyond the life 
//      expectancey of most vehicles).  And 1 meter resolution is more than enough
//      to provide a very accurate GPS calculated odometer reading (at least well
//      within the accuracy of currently available GPS receivers).
//     -The elapsed time unit of measurement has changed from milliseconds to
//      seconds for the properties PROP_ELAPSED_#_LIMIT.  The recording of
//      elapsed time with second precision more practical for vehicle requiring 
//      elapsed time measurements, and fits easily into a single 32-bit integer, 
//      which is easier for porting to other platforms.
//     -Added an optional odometer <meters> field to the end of GPS properties
//      PROP_STATE_GPS and PROP_ODOMETER_#_GPS
// ----------------------------------------------------------------------------

#ifndef _PROPERTIES_H
#define _PROPERTIES_H
#ifdef __cplusplus
extern "C" {
#endif

// ----------------------------------------------------------------------------

/* Maximum ID/name size */
#define MAX_ID_SIZE             20  // Account/Device/Serial/etc.

/* Minimum Unique ID size */
#define MIN_UNIQUE_SIZE         4

// ----------------------------------------------------------------------------
// Custom Property IDs: [00-01 through DF-FF]
//  0001-CFFF : Defined by custom application
// Reserved Property IDs: [00-00, and E0-00 through FF-FF]
//  0000      : Reserved (used to define "No Property")
//  E000-EEFF : Reserved for future use
//  EF00-EFFF : Device configuration
//  F000-F0FF : Misc commands
//  F100-F1FF : Misc, static, read-only information
//  F300-F3FF : Communication
//  F500-F5FF : GPS config
//  F700-F7FF : Motion/Odometer 
//  F900-F9FF : Digital I/O, Elapsed time
//  FB00-FB5F : Analog sensors
//  FB60-FBFF : Temperature sensors
// ----------------------------------------------------------------------------

#ifdef CUSTOM_PROPERTIES
#  include "custom/custprop.h"
#endif

// ----------------------------------------------------------------------------
// Reserved Property IDs: [E0-00 through FF-FF]
// ----------------------------------------------------------------------------
// Properties allow reading state, or setting state, on the device.
// Property attributes typically may be one or more of the following:
//  - Read-Only (cannot be changed by the server)
//  - State (maintains device state, may be read-only by server)
//  - Command (write-only) (invokes an action on the client when set)
//  - Configuration (sets a behaviour attribute)

// ----------------------------------------------------------------------------
// Argument/Value parsing rules:
// 1) For ASCIIZ types, parsing of the ASCII value stops at the first null
//    terminator, or when the end of the data buffer is encountered.  If a null
//    terminator is encountered, then any remaining data after the null may be
//    discarded.
// 2) For numeric/binary types, if the supplied data length is at least the length
//    which is required by the property, then the data is parsed as defined by the 
//    property, and any remaining data may be discarded.
// 3) For numeric types, if the supplied data length is less than what is
//    specified as required by the property, then the supplied data is right 
//    shifted until the proper property required data length is achieved.  If the 
//    property value is signed, then most significant bit of the supplied data is 
//    extended into the bytes comprising the filler.  If the property defines a
//    multiple numeric element, the supplied length is divided evenly by the number 
//    of required elements (any remainder constitutes an error) and the quotient
//    number of bytes is parsed as described above for each element. 0-length data 
//    payloads will be interpreted as '0' numeric values.

// ----------------------------------------------------------------------------
// Notes:
// 1) The client is free to impose whatever limits it deems necessary on the 
//    property values set by the server.

// ----------------------------------------------------------------------------
// Reserved platform configuration properties [E000 through EFFF]

// --- Transport media port config
#define PROP_CFG_XPORT_PORT             0xEF11
    // Description: [optional]
    //      [Read-Only] Serial port to which the transport media device is attached
    // Get Value: 
    //      0:X - [ASCIIZ] string representing the serial port name
    // Notes:
    //      - If needed, this value represents the serial port to which the transport
    //      media device is attached.  For instance, if the system is configured for
    //      GPRS data transport, then this value may represent the serial port to 
    //      which the GPRS modem is attached.
    //      - The read-only attribute of this property should be enforced by the client.
    //      to prevent the server from accidentilly changing this value.

#define PROP_CFG_XPORT_BPS              0xEF12
    // Description: [optional]
    //      [Read-Only] Communication speed (BPS) of the attached transport media device
    // Get Value: 
    //      0:4 - [UInt32] speed of serial port in BPS.
    // Notes:
    //      - The read-only attribute of this property should be enforced by the client.
    //      to prevent the server from accidentilly changing this value.

#define PROP_CFG_XPORT_DEBUG            0xEF1D
    // Description: [optional]
    //      [Read-Only] For use when debugging the transport media device
    // Get Value: 
    //      0:1 - [utBool] Non-Zero if debugging this transport media device
    // Notes:
    //      - Used only when debugging this transport media device.

// --- GPS port config
#define PROP_CFG_GPS_PORT               0xEF21
    // Description: [optional]
    //      [Read-Only] Serial port to which the GPS device is attached
    // Get Value: 
    //      0:X - [ASCIIZ] string representing the serial port name
    // Notes:
    //      - The read-only attribute of this property should be enforced by the client.
    //      to prevent the server from accidentilly changing this value.

#define PROP_CFG_GPS_BPS                0xEF22
    // Description: [optional]
    //      [Read-Only] Communication speed (BPS) of the attached GPS device
    // Get Value: 
    //      0:4 - [UInt32] speed of serial port in BPS.
    // Notes:
    //      - For most GPS receivers, this value is typically 4800 bps.
    //      - The read-only attribute of this property should be enforced by the client.
    //      to prevent the server from accidentilly changing this value.

#define PROP_CFG_GPS_MODEL              0xEF2A  // was 0xEF22
    // Description: [optional]
    //      [Read-Only] The name/type of the attached GPS device
    // Get Value: 
    //      0:X - [ASCIIZ] string representing the name/type of the attached GPS device.
    // Notes:
    //      - This value may be used for custom initialization.
    //      - The read-only attribute of this property should be enforced by the client.
    //      to prevent the server from accidentilly changing this value.

#define PROP_CFG_GPS_DEBUG              0xEF2D
    // Description: [optional]
    //      [Read-Only] For use when debugging the GPS device
    // Get Value: 
    //      0:1 - [utBool] Non-Zero if debugging this GPS device
    // Notes:
    //      - Used only when debugging this GPS device.

// --- General serial port 0 config
#define PROP_CFG_SERIAL0_PORT           0xEF31
    // Description: [optional]
    //      [Read-Only] General serial port 0 name
    // Get Value: 
    //      0:X - [ASCIIZ] string representing this serial port name
    // Notes:
    //      - The read-only attribute of this property should be enforced by the client.
    //      to prevent the server from accidentilly changing this value.

#define PROP_CFG_SERIAL0_BPS            0xEF32
    // Description: [optional]
    //      [Read-Only] Communication speed (BPS) of the attached serial port 0
    // Get Value: 
    //      0:4 - [UInt32] speed of serial port in BPS.
    // Notes:
    //      - The read-only attribute of this property should be enforced by the client.
    //      to prevent the server from accidentilly changing this value.

#define PROP_CFG_SERIAL0_DEBUG          0xEF3D
    // Description: [optional]
    //      [Read-Only] For use when debugging serial port 0
    // Get Value: 
    //      0:1 - [utBool] Non-Zero if debugging this serial port
    // Notes:
    //      - Used only when debugging this serial port.

// --- General serial port 1 config
#define PROP_CFG_SERIAL1_PORT           0xEF41
    // Description: [optional]
    //      [Read-Only] General serial port 1
    // Get Value: 
    //      0:X - [ASCIIZ] string representing this serial port name
    // Notes:
    //      - The read-only attribute of this property should be enforced by the client.
    //      to prevent the server from accidentilly changing this value.

#define PROP_CFG_SERIAL1_BPS            0xEF42
    // Description: [optional]
    //      [Read-Only] Communication speed (BPS) of the attached serial port 1
    // Get Value: 
    //      0:4 - [UInt32] speed of serial port in BPS.
    // Notes:
    //      - The read-only attribute of this property should be enforced by the client.
    //      to prevent the server from accidentilly changing this value.

#define PROP_CFG_SERIAL1_DEBUG          0xEF4D
    // Description: [optional]
    //      [Read-Only] For use when debugging serial port 1
    // Get Value: 
    //      0:1 - [utBool] Non-Zero if debugging this serial port
    // Notes:
    //      - Used only when debugging this serial port.