readme.txt

Open DMT Client C Source code

-----------------------------------------------------------------------------------
Project: OpenDMTP Reference Implementation - C client 
URL    : http://www.opendmtp.org
File   : README.txt
-----------------------------------------------------------------------------------

This is version v1.2.3 update to the OpenDMTP C reference implementation.  This
release contains the following changes (see CHANGELOG.txt for detailed change 
history):
- Added additional logging for any errors returned by 'closedir', 'fflush', 'fclose'.
- Additional changes made to facilitate 'dual transport' support.
- Property 'PROP_COMM_HOST' no longer uses 'localhost' as a default.  Also, if 
  this property remains undefined during deployment, no events will be queued.
- When Geozone arrival/departure 'delay' is in effect, the generated event will
  be the time and GPS fix of the moment that the geozone boundary crossing was
  detected.
- See 'CHANGELOG.txt' for details.

Note: The OpenDMTP Protocol Specification manual, previously part of this package,
has been moved to its own separate downloadable SourceForge package at:
  http://sourceforge.net/project/showfiles.php?group_id=151031

README Contents:
   1) Introduction
   2) OpenDMTP Protocol Overview
   3) Supported Platforms
   4) Supported GPS Devices
   5) Quick-Start Build/Installation
   6) Building OpenDMTP for the GumStix Platform
   7) Using a GPRS Modem
   8) Customizing for Specific Applications
   9) The DMTP Server
  10) Source Directory Layout
  11) Future OpenDMTP Reference Implementation Features
  12) Frequently Asked Questions
  13) Contact Info
  
-----------------------------------------------------------------------------------
1) Introduction:

The "Open Device Monitoring and Tracking Protocol", otherwise known as OpenDMTP(tm), 
is a protocol and framework that allows bi-directional data communications between 
servers and client devices over the Internet and similar networks.  OpenDMTP is 
particularly geared towards location-based information, such as GPS, as well as 
other types of data collected in remote-monitoring devices. OpenDMTP is small, and 
is especially suited for micro-devices such as PDA's, mobile phones, and custom OEM 
devices.

OpenDMTP is a protocol definition and is therefore separate from the implementation
in any specific language.  At this time the OpenDMTP client/server protocol has been
implemented in C, Java, and PHP.  This package includes a reference implementation
of the OpenDMTP protocol written in C, and is intended to be used as a development
"kit" for creating customized feature-rich device monitoring and tracking systems.  
A full reference implementation is included as a starting pointt that provides the 
following motion and odometer features:
  - Start-of-motion events.
  - In-motion events.
  - Stopped-motion events.
  - Dormant events (as a result of non-motion).
  - Odometer events.
  - Geofence arrival/departure.

Here are a few example applications that describe how OpenDMTP can be used:
  - Track the location of your vehicle every minute while it is in motion.  While
    it is stopped, have the vehicle report once per hour.
  - Have your vehicle notify you every 4K miles when it is time to change the oil.
  - Have your vehicle notify you when it arrives at a particular destination.
  - Collect and report telemetry data, such as ice-box temperatures, or fuel level,
    and generate an event when the values are outside of an acceptable range.
  - Have location based data transmitted back to a central server over GPRS for 
    immediate query on a map.
  - Retain the collected data in the vehicle until it returns home, then download
    the collected data via WiFi or BlueTooth.
  - Collect vehicle travel history on an SD flash card, then remove the card from
    the device and place it in a PC for viewing on a Map.

-----------------------------------------------------------------------------------
2) OpenDMTP Protocol Overview:

The protocol was specifically designed as a means to communicate with remote
trackable devices over a high-latency/low-bandwidth media.  Here is a brief
list of some of the supported DMTP protocol features:
  - A Simple set of packet types that provide a rich set of features.  See the 
    source file "base/packet.h" for a list of client and server packet types.
  - Supports both binary and ascii encodings (Base64 and Hex).  Based on the 
    transport media used, and the specific requirements, the client can decide 
    which packet encoding it wishes to use.
  - Supports both Duplex and Simplex data communication.  Duplex connections
    allow the server to provide acknowledgment and reconfiguration information
    to the client, however Simplex connections (eg. UDP) may be desirable or 
    even necessary in some circumstances.
  - Supports periodic, intermittent, and dedicated connections types.
    Whether communicating periodically over a wireless GSM/GPRS media, or
    intermittently over a BlueTooth media, the protocol is adaptable to all
    connection types.
  - Highly extensible.  New client property types, transport media types, and
    GPS rule modules, can easily be supported in the protocol.
  - Rich set of remotely settable client-side properties.  Including setting
    many different types of configuration properties or sending special commands
    to the client. See the source file "base/props.h" for a list of the standard
    property types.
  - Supports custom event packets and custom event packet negotiation. Different 
    applications will need different types of data from the client device.  The 
    client side of the protocol provides for custom 'event' packet definitions
    containing only the data it needs to transmit.  If the server does not 
    understand a clients custom 'event' packet, the protocol provides a means for 
    the client to supply a custom definition template to the server so that the 
    server is able to accurately parse the custom packets.  This is known as 
    "custom event packet negotiation".

The OpenDMTP protocol definition reference manual can be found in a separate 
"protocol-spec" package which can be downloaded from SourceForge at this location:
  http://sourceforge.net/project/showfiles.php?group_id=151031

-----------------------------------------------------------------------------------
3) Supported Platforms:

This reference implementation is currently designed to compile on Linux and Cygwin 
platforms using the 'gcc' compiler, and has been tested on several Linux 
distributions (including embedded devices) as well as Windows XP (with Cygwin 
installed).

This reference implementation now also will build on Window CE/Mobile platforms
using the Microsoft eMbedded Visual C++ compiler.   See the included document
"HW6945.txt" for information regarding how to build the OpenDMTP reference 
implementation for the new Hewlett Packard hw6945 phone with an embedded GPS
receiver.

If you have another platform that you would like the DMTP client to run on, please 
let us know and we'll work together to make this happen.

-----------------------------------------------------------------------------------
4) Supported GPS Devices:

The means of obtaining GPS information is not defined by the protocol.  However,
for this reference implementation, any GPS device that outputs standard NMEA-0183 
compliant GPS records over an RS232 serial port can be used.  USB GPS modules can 
be supported as well provided the operating system provides an RS232 emulation 
driver and can assign the USB device to a local RS232 port name.

Example RS232 device(s);
- Garmin GPS18PC with a cigarette lighter adapter for power, and a DB9 serial
  interface connector.

Example USB device(s):
- Microsoft branded Pharos "GPS-360":  Works as-is on Windows XP (via serial port
  interface).  Also works under Linux using the "pl2303" USB Serial kernel driver 
  with modern Linux kernels.
- Other USB GPS devices using the Prolific PL2303 chip should also work under Linux 
  using the "pl2303" driver [reportedly working devices can be found from Aten (the 
  UC-232) and IO-Data].

-----------------------------------------------------------------------------------
5) Quick-Start Build/Installation:

  1) Unzip the OpenDMTP C client package in a convenient directory.
  2) Compile the application for your target environment.  Examples:
      - To compile on Linux enter "make dest=linux dmtp"
      - To compile on Cygwin enter "make dest=cygwin dmtp"
  3) Plug in a supported GPS device into a known RS232 serial port.
  4) Start the dmtp program as follows:
       ./build_lin/dmtpd -debug -pf debug.conf -gps <port>
     or  
       ./build_cyg/dmtpd -debug -pf debug.conf -gps <port>
     Where "<port>" is the serial port of the GPS module specified in the form
     com3, com4, etc., or ttyS2, ttyS3, etc.   The option "-debug" and the option
     "-pf debug.conf" (which loads the debug property file removing the connection
     restrictions) are for debug/testing use only and should be removed when used
     in a production environment.
  5) As shipped, start/stop and in-motion packets will be sent to the file 
     "dmtpdata.dmt" in the current directory. (Drive around with a laptop to obtain 
     tracking information).  A file parser is also provided by compiling the make 
     target 'parsfile' (eg. "make dest=linux parsfile").  This command will parse
     the event packets found in the file and generate CSV records containing the
     event data.  Run the command with the '-help' option (e.g. "parsfile -h") for 
     additional information. (You may modify the code as necessary to output the
     fields and format needed for your application).
  6) If using a socket or GPRS based communication with a server, then you may
     wish to relax the default "connection accounting" restrictions when debugging
     your application.   The property defaults can be overridden by placing a file 
     named "props.conf" in the current directory with "<PropertyKey>=<Value>" 
     entries (see 'propman.c' for a full list of valid <PropertyKey> names).  For 
     debugging purposes, create a "props.conf" file with the following contents:
        # --- connection parameters
        # - maximum number of total connections, duplex connections, and time frame
        # - ("1,1,0" means "no maximum")
        com.maxconn=1,1,0
        # - absolute minimum time delay between transmissions
        com.mindelay=0
        # - minimum time delay between transmissions for non-critical events
        com.minrate=0 
     Use this ONLY for debugging purposes, and not for production use. 
     The default property override config file name is "props.conf", however this 
     can be changed on the command line by adding the argument "-pfile ./props.conf" 
     and changing "./props.conf" to the name of the file you wish to load instead 
     of the default.

Thread support is enabled by default (in "make/options.mk"), and 'malloc' is used 
for memory allocation in some of the source modules.  These features, and others, 
can be enabled/changed by modifying the header file 'custom/defaults.h', or the
common makefile "make/common.h", and re-compiling the DMTP client executable.

-----------------------------------------------------------------------------------
6) Building OpenDMTP for the GumStix Platform: