readme.txt

Open DMT Client C Source code

The GumStix single board computer (http://www.gumstix.com) makes a perfect reference 
platform for the OpenDMTP protocol and reference implementation.  With the addition 
of a GPS device, it can be used to record tracking information which can be 
transmitted to a back-end server, sent over BlueTooth, or recorded onto an SD flash 
card.  GumStix is planning on releasing a daughter board soon with an on-board GPS
receiver that is ready made for the OpenDMTP reference implementation.

The OpenDMTP reference implementation already provides build targets for the
GumStix platform.  To build the OpenDMTP reference implementation for the GumStix 
platform, please refer to the included document "gumstix/GumStix.txt".

-----------------------------------------------------------------------------------
7) Using a GPRS Modem:

Support for transmitting collected data wirelessly over a GPRS modem is available 
in this reference implementation.  To build the OpenDMTP reference implementation 
with this feature turned on, change the "custom/defaults.h" file to uncomment the 
compile time variable "TRANSPORT_MEDIA_GPRS", then compile the client as indicated 
above.  (Note: "dmtp_gprs" is also an acceptable make target to do the same.)
Then start the 'dmtpd' client with the name of of the serial port were the GPRS 
modem is attached.  For example:
   % dmtpd -gps <port> -gprs <gprs_modem_port> -server <dmtp_server> <dmtp_port>
   
Currently, the specific GPRS modem supported is the BlueTree M2M Epress GPRS.
Internally this is a Wavecom modem, thus it may be possible to use any Wavecom 
GPRS modem, but this has not been verified.

-----------------------------------------------------------------------------------
8) Customizing for Specific Applications:

This reference implementation is highly customizable for many different types of 
devices and requirements.  This reference implementation currently ships with 
support for communicating with a DMTP service provider over a straight socket, a
GPRS modem, or just simply writing GPS events to a local file (the default 
configuration specified in 'default.h'). However, many other transports media types 
are also possible, such as communicating over BlueTooth to another device.

To implement your own customized configuration, start with the following files:
   src/custom/defaults.h
   src/custom/startup.c

To implement new transport support, add the files to custom/transport/. and modify 
the following files accordingly:
   src/custom/defaults.h
   src/custom/startup.c
   src/custom/transport.c
   src/custom/transport.h

For instance, to build the reference implementation with socket support modify 
'defaults.h' and uncomment 'TRANSPORT_MEDIA_SOCKET', then recompile. (The host:port 
definitions currently defaults to "localhost" and port 31000, and can be changed in
the source file "custom/startup.c").  A simple socket based server is also provided 
by compiling the make target 'sockserv'.

-----------------------------------------------------------------------------------
9) The DMTP Socket Server:

A simple TCP socket transport server is provided in this reference implementation
to allow testing the DMTP client socket transport.  This server implementation 
currently accepts only a single DMTP client connect at a time, and does not support
custom event packet negotiation (however, custom event packet types can be added
explicitly to the server if necessary).

To build the DMTP TCP server, issue the command "make dest=linux sockserv" (or
specify another destination platform as necessary).  The server can be started
with the following command:
    sockserv -tcp <socketPort>
Where <socketPort> is the local port to which to bind and make the service
available.  This port must be the same as the client will be using to transmit
data (the default port used in the client is 31000).

The 'sockserv' server currently writes received events to the file "sockserv.dmt"
in the current directory, however this can be overridden with the "-output" option:
    sockserv -tcp <socketPort> -output myfile.dmt
In this configuration, the data written to this file is parsable with the command
'parsfile' as described above.  To configure 'sockserv' to write events in CSV
format specify 'csv' after the filename:
    sockserv -tcp <socketPort> -output myfile.csv csv

The DMTP client must also be configured to reference the host that the server is
running on.  Typically, when testing and debugging connections, this will be
"localhost".

Since this server only supports TCP connections, the client should insure that
only 'Duplex' connections are used to transmit data. This reference implementation
provides a simple way to force duplex-only connections by simply supplying the
argument '-duplex' as a command-line option when starting the DMTP client.

-----------------------------------------------------------------------------------
10) Source Directory Layout:

./src/
    DMTP source directory.

./src/base/
    Basic DMTP client-side support source files.

./src/modules/
    Standard GPS event modules.
    - Motion and Odometer modules are provided in the reference implementation.

./src/tools/
    Miscellaneous tools and utilities.

./src/custom/
    Custom DMTP reference implementation.

./src/custom/transport/
    Custom transport layer implementation.
    - File and Socket transports are provided in the reference implementation.

./src/parsfile/
    Stand-alone support for parsing DMTP event packets from a file.
    - All non event packets are ignored.
    - Custom event packet formats are not currently implemented.
    - This implementation supports all packet encoding formats.
    
./src/server/
    Common server support source files.

./src/server/serial
    Simple stand-alone serial port transport server.
    - Suitable for use with serial port communications
    - Custom event packet negotiation is not implemented.
    - File download is supported.

./src/server/sock
    Simple stand-alone socket transport server.
    - This server provides a simple TCP socket transport (UDP not yet implemented).
    - Custom event packet negotiation is not implemented.
    - File download is not fully supported.

-------------------------------------------------------------------------------
11) Future OpenDMTP Reference Implementation Features:

The following items are also in the works for future OpenDMTP support:
  - Additional platform support.
  - Free DMTP Internet service providing Internet access to GPS tracking data.
  - Etc!

-------------------------------------------------------------------------------
12) Troubleshooting:

Here are a list of a few of the most frequently asked questions:

- Q: I've started it up and it appears to be working, but I'm not getting any
     GPS fixes.
  A: Several possibilities here.  Make sure that the GPS receiver itself is
     working.   Use a terminal emulator, such as Hyper terminal, to test that
     you are seeing valid GPS 'fix' information coming from the receiver.
     Also check to see that the communication settings aren't so restrictive that
     they aren't allowing data to be transmitted for extended periods of time.
     The config file 'debug.conf' is included that will remove all communication
     restrictions for testing and debugging purposes.
     
- Q: I've tried compiling for file transport media, then tried compiling for 
     socket based transport media, but the client is no longer running properly.
  A: Make sure you always issue a "make clean" when switching from one type of
     transport media to another.  Some object files may be left around that 
     may need to be recomplied when switching to a different transport media.

- Q: Can the protocol be extended to add new status types?
  A: Absolutely, the protocol was designed specifically with extensibility in
     mind.  New status types and even custom event packet definitions can 
     easily be added to the OpenDMTP implementation.
     
- Q: Do you already have OpenDMTP working on device XXXXXX?
  A: Probably not yet.  There are hundreds of devices out there, most already 
     have their own proprietary protocol, and we are learning about new devices
     every day.  For OpenDMTP to work on a device, it will likely need the 
     cooperation of the hardware manufacturer.  We see a lot of devices that 
     have a less-than-optimal communication protocol, and we are attempting to
     work with those we can to get OpenDMTP implemented on them.
     
- Q: I see that your example OpenDMTP tracking is using Google Maps. Can it use
     other mapping services as well?
  A: OpenDMTP is a protocol definition and is actually independent of any back
     end support services.  Google Map was used show to showcase the features of
     OpenDMTP because it provides a great mapping platform with a great API.  
     However, with the proper interface, any web-based mapping service can also
     be used, provided you have the proper subscription to their service and 
     have implemented their custom mapping API.

- Q: Can OpenDMTP be used for in-car navigation?
  A: While OpenDMTP probably can be used for such a platform, there are other
     possibly better equipped systems and protocols out there for providing that 
     service.  OpenDMTP was designed to efficiently transmit GPS based events to 
     a remote server (via GPRS, 802.11, BlueTooth, etc) for external analysis.  
     In-car navigation typically requires more elaborate hardware with a display 
     screen, internal mapping database, and possibly a keyboard, and protocol
     efficiency may not be as much of an issue.

-------------------------------------------------------------------------------
13) Contact Info:

Please feel free to contact us regarding questions on this package.  Or if you
would like to be be kept up to date on the progress of this project, please let
us know.

Thanks,
Martin D. Flynn
[e-mail]