= Jenprog - programmer for jennic chips =

 Jenprog is a command line driven programmer for jennic Wireless
Microcontrollers. It supports programming through serial interfaces and over
ipv6. Furthermore it has a special mode for Ftdi-Chip Serial board designs that
put the Jennic chip into reset over the DTR/DSR lines.

== Installation ==

  Just run:
 $ python setup.py install

  This should alert if the pyserial package is not installed. You can get it
with:
 $ easy_install pyserial

=== DTR/DSR line ftdi designs ===

 This step is completly optional and you'll only need this if you have a design
that puts the jennic into reset via DTR/DSR lines. For this you need to install
the pyftdi library supplied with this project (please note that this lib has
only been tested under linux):
 $ cd pyftdi/
 $ scons install

 For this command to be succesful, the following projects have to be available:
  - swig (http://www.swig.org)
  - libftdi (http://www.intra2net.com/en/developer/libftdi)
  - scons (http://www.scons.org)

 Using the ftdi connection is completly optional though.

== Usage ==

Usage: jenprog [options] <file>

Options:
  -h, --help            show this help message and exit
  -a ADDR, --address=ADDR
                        start reading at address
  -l LEN, --len=LEN     number of bytes to read
  -m MAC, --mac=MAC     reset the mac addr
  -k KEY, --key=KEY     reset the license key
  -v, --verbose         print send and received packets
  -y, --verify          also verify after writing
  -s, --show            show mac address and license key
  -e, --erase           erasing the flash after reading mac and license key
  -c CONN, --connection=CONN
                        connection implementation (serial,ipv6,ftdi) [default:
                        serial]
  -t TARGET, --target=TARGET
                        target for connection

  Calling jenprog without any file argument will read the contents of the flash
to standard output. Calling it with a file argument will delete the flash and
reprogram with the supplied file.

WORD OF CAUTION:
 * be sure to read your licence key and mac address prior to any attempt to
   reprogram the jennic as it will be deleted and reprogrammed every cycle. So
   if your programming is stopped half-way mac and license key will be lost!
 * there are no sanity on the file itself, jenprog will happily write crap to
   jennics flash memory.

  Standard cycle of reprogramming on linux looks like this:

 $ jenprog -s
 flash: ST M25P10-A
 mac: 0x00158d0000058448 license: 0x000000000000000000000

 $ jenprog my-example-program.hex
 0%..10%..20%..30%..40%..50%..60%..70%..80%..90%..done - 2.55 kb/s - writing mac address and key..done

  For win32 this should be something like:
 $ jenprog -t COM1 my-example-program.hex

=== Putting the Jennic module into programming mode ===

  On certain type of boards you have to put the module into programming mode,
prior to reprogramming the moduls. On the jennic demokit boards this is done by
pressing 'reset' and 'program' together and releasing the 'reset' button prior
to the 'program' button.

  When programming over the ipv6 or ftdi connection this is not needed as
entering the bootloader will be done automatically.

=== Configuring connection ===

  Jenprog supports three ways of connecting to your device. Through serial
ports, ftdi and ipv6. The Type of connection is determined by the '-c'
parameter. The target parameter depends on the chosen connection. For serial
connection this is the serial port to use, for ipv6 this is the ip-address of
your device, for ftdi this is the number of connected devices. Serial connection
is the default, for example to program through the second USB serial connector,
you could use:

 $ jenprog -c /dev/ttyUSB1 <program-file.hex>
 0%..10%..20%..30%..40%..50%..60%..70%..80%..90%..done - 2.55 kb/s - writing mac address and key..done

Programming with a ftdi chip and the DTR line connected to SPIMISO and DSR to
the RESET line works like this:

 $ sudo jenprog -c ftdi <program-file.hex>
 0%..10%..20%..30%..40%..50%..60%..70%..80%..90%..done - 2.55 kb/s - writing mac address and key..done

Using ipv6 works similar to this:

 $ jenprog -c ipv6 -t <ip-address> <program-file.hex>
 0%..10%..20%..30%..40%..50%..60%..70%..80%..90%..done - 5.25 kb/s - writing mac address and key..done

=== Showing/Resetting the mac address and license key ===

 Jennic modules store their ieee802.15.4 mac address in a special region in the
flash. Futhermore the license key for their Zigbee stack can also be found
there. To show them you need to put the Jennic module into programming mode.
Afterwards call jenprog with your configuration with '-s' parameter. For example
over ipv6:

 $ jenprog -c ipv6 -t <ip-address> -s
 flash: ST M25P10-A
 mac: 0x00158d0000058448 license: 0x000000000000000000000

which will output the type of flash this module includes, its mac address and
its license key.


== License ==

Copyright (c) 2011
Telecooperation Office (TecO), Universitaet Karlsruhe (TH), Germany.
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above
   copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials provided
   with the distribution.
3. Neither the name of the Universitaet Karlsruhe (TH) nor the names
   of its contributors may be used to endorse or promote products
   derived from this software without specific prior written
   permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Author(s): Philipp Scholl <scholl@teco.edu>