Specs
Samples
Documents
FAQ
Downloads
Support
This page provides additional information on AVIDdirector. These are Frequently Asked Questions regarding AVIDdirector's operation and programming.
FAQ: Accessing Modem Return String
FAQ: Directory Structure for AVIDdirector
FAQ: Directory structure description of AVIDdirector-M2M install
FAQ: How does AVIDdirector differ from J2ME based Devices?
FAQ: IDEs to use
FAQ: Imsys SNAP mailing list Archive
FAQ: Is the antenna connection on the AVIDdirector male or female?
FAQ: Options to test your radio (testradio)
FAQ: Sample DOS Batch files and ANT scripts
FAQ: Send a M2MXML status request to the AVIDdirector
FAQ: Serial1 won't operate at 4800 baud
FAQ: SNAP Error Codes - What Do They Mean?
FAQ: Status LEDs - What Do They Mean?
FAQ: Watchdog Timer
FAQ: What is M2MXML™?
FAQ: Serialport Mappings
FAQ: SnapDev Firmware bootloader does not respond
FAQ: System LED Error Codes
FAQ: Why does my program not run on AVIDdirector-M2M?
 
 
Accessing Modem Return String

How to access the modem responses from the AT_Radio_Modem.sendRadioCommand?

If it is a response that doesn't start with a " " (e.g. the AT GMM command returns the name of the modem), then you can use the methods:

String getSendRadioCommandResponseRaw()
String getSendRadioCommandResponse()

to return the entire response from the modem, including the "OK".

Responses from the MultiTech modems, which start with a (e.g. CGREG: 4) and are almost all of the modem status responses, can be received if your class implements the interface com.avidwireless.radio.RadioModemListener the method modemStatus (String statusType, String statusData) will be called every time a modem status is received. Your class has to be registered using the Radio method addRadioModemListener(RadioModemListener).

Directory Structure for AVIDdirector

Below is a description of the files present on the AVIDdirector-M2M. Note that some of the names may have changed from earlier releases, but it should be obvious which directory they match with here.

AVIDirector /      Contains a copy of the files are they on the AVIDirector-M2M Flash system

 avidwireless/

classes/  User written classes
ADM2MLib.jar AVIDirector base classes

 root/

  M2MApp.bak  Backup configuration file
  M2MApp.default Configuration file default
  M2MApp.ini  Configuration file
  M2MApp.jar  M2MApplication Framework application

 system/

  classes/  Special snap classes
  access.ini  Sets user privileges
  boot.ini  Boot-up parameters
  dalsemi.jar  TINI compatibility JAR file
  group.ini  User groups
  hostname.ini Sets hostname for TCP/IP
  ish.ini   ISH configuration - paths, classpath
  passwd.ini  User password
  reboot.ini  Programs run for 'reboot' command
  snap.gpx  SNAP program (JVM)
  snap.ini  Java parameters (heap)
  snap.jar  SNAP Java J2ME CLDC classes
  snap.ver  Version information
  startup.ini  Programs to run at startup.

 tmp/

AVIDirector-Software/    Contains Java source files for the AVIDirector-M2M Framework

ADLibrary/
IODevices/
JavaDocs/
kXML/
M2M_IO/
M2MApp/
MinML/
Radios/
SNAP J2ME/

Documentation/     Various documentation files

M2MXML/     M2MXML specification

SNAP_Software/    Source to SNAP J2ME CLDC files

bin/
classes/
doc/
samples/
src/

SNAPDev_Files/   File to reload the device. The main files are:

AVIDM2M_Baseconfig_1_5_0.snp  Loads basic SNAP software. First file loaded for complete reload
AVIDM2M_SnapLib_1_5_0.snp Loads snap.jar and dalsemi.jar  
AVIDM2M_AVID_Files_1.5.0.snp - Loads AVIDirector-M2M files, ADM2MLib.jar and M2MApp.jar

These files are loaded using the SNAPDev boot loader. This is accessed from SNAPDev by pressing the Reset icon or pressing F5 to enter the bootloader mode. This looks like:

SNAP loader v 0.1.10 (Build date: Aug 19 2005 19:40:48)
$

Directory structure description of AVIDdirector-M2M install

This page describes the files present on the AVIDdirector-M2M. Note that some of the names may have changed from earlier releases, but it should be obvious which directory they match with here.

AVIDirector /                  :Contains a copy of the files as they are on the AVIDdirector-M2M Flash system

 avidwireless/

   classes/         :User written classes
   ADM2MLib.jar     :AVIDirector base classes

 root/

   M2MApp.bak       :Backup configuration file
   M2MApp.default   :Configuration file default
   M2MApp.ini       :Configuration file
   M2MApp.jar       :M2MApplication Framework application
 
  system/

    classes/       :Special snap classes
    access.ini     :Sets user privileges
    boot.ini       :Boot-up parameters
    dalsemi.jar    :TINI compatibility JAR file
    group.ini      :User groups
    hostname.ini   :Sets hostname for TCP/IP
    ish.ini        :ISH configuration - paths, classpath
    passwd.ini     :User password
    reboot.ini     :Programs run for 'reboot' command
    snap.gpx       :SNAP program (JVM)
    snap.ini       :Java parameters (heap)
    snap.jar       :SNAP Java J2ME CLDC classes
    snap.ver       :Version information
    startup.ini    :Programs to run at startup.

 tmp/

AVIDirector-Software/    :Contains Java source files for the AVIDdirector-M2M Framework

  ADLibrary/
  HelpFiles/
  IODevices/
  J2ME_Samples/
  JavaDocs/
  kXML/
  M2M_IO/
  M2MApp/
  MinML/
  PSoC_Files/
  Radios/
  Sample_M2Mlets/
  Samples/
  SNAP J2ME/
  Ted/
  Terminal/

Documentation/       :Various documentation files

SNAP_Software/      :Source to SNAP J2ME CLDC files

  bin/
  classes/
  doc/
  samples/
  src/

SNAPDev_Files/     :File to reload the device. The main files are:

  AVIDM2M_Baseconfig_1_5_0.snp    :Loads basic SNAP software. First file loaded for complete reload
  AVIDM2M_SnapLib_1_5_0.snp       :Loads snap.jar and dalsemi.jar 
  AVIDM2M_AVID_Files_1.5.0.snp    :Loads AVIDirector-M2M files, ADM2MLib.jar and M2MApp.jar

These files are loaded using the SNAPDev boot loader. This is accessed from SNAPDev by pressing the Reset icon or pressing F5 to enter the bootloader mode. This looks like:

SNAP loader v 0.1.10 (Build date: Aug 19 2005 19:40:48)
$

How does AVIDdirector differ from J2ME based Devices?
How does AVIDdirector differ from J2ME based Devices?
AVIDdirector
J2ME Based Devices
Direct Execution of Java Instruction Set
Interpreted Execution via JVM
Sun CLDC Certified
Sun CLDC Certified
8 to 16 Mbytes RAM
64K to 1 Mbyte RAM
10 Serial Ports, Capable of 931 Kbaud
Serial Ports are Not Standard in J2ME - Some Devices Provide for 1 Port
2 to 64 MB Flash for Pprogram and Data Storage
128K to 3 MB Flash for programs and data (data may be limited to a subset of Flash memory on some Devices)
Debug Port Allowing Single Step Execution, Breakpoints, Variable and Reister Inspection Limited debug, often only by using screen dialogs or printfs to serial port
Can call C or Assembler Modules for Optimized Operations
No Support for JNI (Java Native Interface)
I²C, SPI, 1-Wire, and CAN hardware Interfaces
No Hardware Interfaces
Up to 128 Concurrent Executing Programs
Often Only Single Program Executing
Javax.comm, serial port allowing full hardware control of serial port, along with J2ME Connection Support J2ME Connection Interface. No Hardware Control
File System, Including MMC Card with FAT File
No File System or External Memory
Can Run JDBC SQL Databases (DB2, Pointbase etc.) Along with J2ME RMS J2ME RMS Database (Limited Database Functionality)
Watchdog Timer with Automatic Reboot
No Watchdog. Manual Termination of Application
HTTP, FTP, Telnet Servers Standard
No Servers
HTTP, TCP/IP, UDP, PPP, Mobitex Protocol Support
HTTP Protocol Support Only
Java.net Socket and ServerSocket
Sockets Fully Supported in J2ME, Though Not Supported on Some Devices
Servlet 2.2 Engine (With 3rd Party Servlet)
No Servlet Support
Full Access to System Hardware, Including I/O Ports, Memory and Serial Devices No Hardware Access - Limited to J2ME Sandbox
External Hardware Interrupts, Including Waking Application on Interrupt
No Hardware Interrupts
All J2ME Data Types, including Long, and Float
J2ME Defined Dataypes (Byte, Short, Int)
Supports Many J2SE Classes Along With J2ME
Only J2ME Support
SHA-1 Hash (FIPS 180-1 Compliant)
No Hash Security Classes
Programmatic Shutdown and Reboot of Controller and Java Subsystem
No Programmatic Control of JVM
Unix Like Shell for Command Line Support
No User Shell
Multiple Users and Password
No User Account System
Multiple Account File Security
No User Account Security
IDEs to use

You can use any Java IDE with the AVIDdirector. The 2 important things are:

  • The compiler needs to specify the snap_rt.jar (it is in the AVIDirector-M2M\AVIDirector_Software\lib directory) in the BOOT CLASSPATH (for the Sun compiler ,it is "javac -boothclasspath C:\AVIDirector-M2M\AVIDirector_Software\lib\snap_rt.jar").
  • You also need to include the ADM2MLib.jar and M2MApp.jar in the same directory in your standard Java Classpath for compiling. 

Some IDEs are:

They are both free downloads. You may want to also get Ant (http://ant.apache.org ) for building your software. AVIDwireless' samples come with Ant build scripts (build.xml), so you can use them as a template for your own code.

Imsys SNAP mailing list Archive
Go to http://www.imsystech.com/forum/archive.pop  for SNAP mailing list archive. It contains information and questions about the SNAP design and CJip processor used in AVIDdirector-M2M
Is the antenna connection on the AVIDdirector male or female?

This page provides a chart showing the current mappings for the antennas of different types of radios on an AVIDdirector-M2M device. They are all SMA connectors.

Radio AVIDdirector side Antenna
GPRS female male
CDMA female male
iDEN female male
GPS female male
900 Mhz ISM male female
2.4 Ghz ISM male female
Bluetooth male female
802.11 male female
ZigBee male female

These mappings can be modified by AVIDwireless for your particular unit, upon request.

Options to test your radio (testradio)

This page lists the options accepted by the testradio program through command line & their possible values. Testradio program is provided to test any radios that may be connected to the AVIDdirector in a stand alone mode. It is useful in establishing basic connectivity & test basic communication which helps in setting up or debugging a radio. Before running the testradio program you will need to know the type of radio. You may also need to know the baud rate, the serial port & the hardware mapping or you can use the default values. Default values will be used for options that are not specified though the command line.

To get the options of the testradio program:

 /root > testradio -?
Starting TestRadio ...
Options are [-c configFile][-b baudRate][-s serialPortNAme][-r atmodem|gprs|cdma|bluetooth|aerocomm|xport]
            [-m RS232|RJ12|RADIO|RADIO2|RADIO3|EXTA|EXTB|Other hardware mapping]
            [-d DNS][-u PPPUsername][-p PPPPassword]
            [-t pollTime][-B Start/Stop PPP background thread]
  (for GPRS) [-a APN][-C SMSC][-1 SIMPUK1][-2 SIMPUK2]

Below is a description of the options.

-? To see the list of options. 
-r   This is used to specify the type of radio to be tested. Acceptable option values are: aerocomm, cdma, iden, gprs, bluetooth, xport. atmodem.
-C   This option ignores the default configuration file. This also applies to GPRS radio, for SMSC option for GPRS see below.
-c configFilename Use the following filename to read the configurations. The default configuration file is M2MApp.ini
-b baudrate Use the given baudrate. Overrides the baudrate in M2MApp.ini or given configuration file. Acceptable values are: 4800, 9600, 19200, 38400, 57600, 115200.
-s serialPortName Use thie given serialport name to start the radio. Acceptable values are: serial1, serial2 & serial3.
-m radioName Map the specified serial port the the radio specified by this option. Accpetable values are: RADIO, RADIO2, RADIO3, EXTA, EXTB, RS232, RJ12.
-d DNSvalue  DNS value to use for the PPPconnection. (Does not apply to bluetooth or aerocomm modems).
-u userName UserName value to use for the PPPconnection. (Does not apply to bluetooth or aerocomm modems).
-p password Password value to use for the PPPconnection. (Does not apply to bluetooth or aerocomm modems).
-t  nnn Server poll time in seconds.
-B  Starts PPPconnection if its not runnning or stops the PPP thread if it is running in the background. (Does not apply to bluetooth or aerocomm modems).

The following options can ONLY be used for GPRS modems

-a nnnnnnn  APN value to be used.
-S nnnnnnnnn SMS Center value to be used. The options is '-S', the list printed by testradio -? has a typo whichn will be released in later versions of AVIDdirector software.
-1 nnnnnnnn SIM pin 1 value to be used.
-2 nnnnnnn SIM pin 2 value to be used
Sample DOS Batch files and ANT scripts

Below are some examples of DOS batch files and ANT scripts to compile and preverify your AVIDdirector-M2M projects.

Compiler batch file to compile and generate a Preverified file (avoid the No Verified file problem):

REM Set the Build Classpath
set BOOT_CLASSPATH=..\lib\snap_rt.jar
set BUILD_CLASSPATH=%BOOT_CLASSPATH%;..\lib\ADM2MLib.jar;..\lib\M2MApp.jar
set JAVAC=javac
set PREVERIFY=..\bin\preverify.exe
REM
REM Compile the app
%JAVAC% -target 1.1 -source 1.3 -sourcepath source -d classes -bootclasspath %BOOT_CLASSPATH% -classpath %BUILD_CLASSPATH% source\*.java
REM
REM Now Preverify to avoid Verification errors (needed for J2ME)
%PREVERIFY% -classpath %BUILD_CLASSPATH% -d pvClasses classes
REM
pause

And an ANT script to compile the Samples directory:

<project name="AVIDirector-M2M Samples" default="compile" basedir=".">
  <description>
   Build file for AVIDirector-M2M Samples
  </description>

 <!-- Set propreties for this build -->
  <property name="jarFile"  value="Samples.jar"/>

 <!-- set global properties for this build -->
  <property name="src"    value="source"/>
  <property name="classes"   value="classes"/>
  <property name="verClasses"  value="pvClasses"/>
  <property name="ProjectDir"  location=".."/>
  <property name="bin"     value="${ProjectDir}/bin"/>
  <property name="lib"     value="${ProjectDir}/lib"/>
  <property name="preverify"   value="${bin}/preverify.exe"/>
  <property name="bootclasspath" value="${lib}/snap_rt.jar"/>
  <property name="ADM2MLib.jar" value="${lib}/ADM2MLib.jar"/>
  <property name="M2MApp.jar"  value="${lib}/M2MApp.jar"/>
  <property name="build.debug"   value="on"/>
  <property name="build.debuglevel" value="lines,vars,source"/>
  <!-- Locations of the Directories in this project -->
  <property name="Adlibrary"   value="${ProjectDir}/Adlibrary"/>
  <property name="IODevices"   value="${ProjectDir}/IODevices"/>
  <property name="kXML"     value="${ProjectDir}/kXML"/>
  <property name="M2M_IO"    value="${ProjectDir}/M2M_IO"/>
  <property name="M2MApp"    value="${ProjectDir}/M2MApp"/>
  <property name="MinML"    value="${ProjectDir}/MinML"/>
  <property name="Radios"    value="${ProjectDir}/Radios"/>
  <property name="Terminal"    value="${ProjectDir}/Terminal"/>

 <path id="build.classpath">
   <pathelement path="${bootclasspath}"/>
   <pathelement path="${ADM2MLib.jar}"/>
   <pathelement path="${M2MApp.jar}"/>
  </path>

 <target name="init">
   <!-- Create the time stamp -->
   <tstamp/>
   <buildnumber/>
  </target>

 <target name="compile" depends="init" description="Compiling" >
   <echo message="Compiling..."/>
   <!-- Compile the java code from ${src} into ${classes} -->
   <mkdir dir="${basedir}/${classes}"/>
   <!-- Path reference for this project -->
   <javac source="1.3" target="1.1"
    bootclasspath="${bootclasspath}"
    srcdir="${basedir}/${src}"
    destdir="${basedir}/${classes}"
    debug="${build.debug}" debuglevel="{build.debuglevel}"
    includeAntRuntime="false" >
    <classpath refid="build.classpath"/>
   </javac>

  <exec executable="${preverify}" failonerror="true">
    <arg value="-classpath"/>
    <arg pathref="build.classpath" mce_href="build.classpath"/>
    <arg line="-d ${basedir}/${verClasses}"/>
    <arg value="${basedir}/${classes}"/>
   </exec>
   <sleep seconds="2"/>
  </target>

 <target name="jar" depends="compile" description="Building Jar file" >
   <echo message="Building ${jarFile}"/>
   <jar destfile="${jarFile}" >
     <fileset dir="${basedir}/${verClasses}"/>
   </jar>
  </target>

 <target name="clean" description="clean up files" >
   <!-- Delete the ${classes} and ${dist} directory trees -->
   <delete dir="${basedir}/${classes}"/>
   <delete dir="${basedir}/${verClasses}"/>
  </target>

</project>

Important points:

  • This assumes the directory is in AVIDirector-M2M\AVIDirector_Software (wherever the AVIDirector-M2M software was installed. It uses the following subdirectory structure:
    • source - Source *.java files
    • classes - Java compiled classes
    • pvClasses - Verfified classes
  • The directory above contains the directory 'lib' which has snap_rt.jar, ADM2MLib.jar and M2MApp.jar in it. Note that the bootclasspath and classpath have to be a single string entry with ';' or ':' (for Unix) between the files. Each Jar file must be listed individually; just listing the directory with Jar files does not work (it would work with a directory of separate class files).
  • We recommend using Sun's 1.4 JSDK release, not 1.5 (aka Tiger or Java 5).
  • You need the '-target 1.1' to generate J2ME compatible bytecodes. The '-source 1.3' is required for JSDK 1.5 and optional for JSDK 1.4
  • The bootclasspath entry on the Java compiler ensures that only API calls compatible with J2ME are done. Without this, you could write an application using a J2SE specific API call, it would compile and preverify correctly, but give a Java.lang.error when run.
Send a M2MXML status request to the AVIDdirector
The AVIDdirector has an internal "Sensor" called Status (com.avidwireless.avidirector.iodevice.Status). This provides the following statuses:
  • RSSI - Current signal strength on the radio of the closest base stations
  • LOG - Listing of the last 10 log entries
  • UPTIME - How long the AVIDdirector has been operating since the last reset/power on
  • VERSION - Versions of software on the device
  • MEMORY - Amount of Flash, RAM and free Heap on the device.

Here is an example to get the memory. The seq value shown here is some arbitrary value.  

<M2MXML ver="1.1"><Command name="perceptRequest"seq="3608"address="STATUS.MEMORY"/></M2MXML>  

Here is setting a configuration command to set the configuration to report every 4 minutes (240 seconds)  

<M2MXML ver="1.1"><Command name="setConfiguration" seq="3609" address="STATUS.MEMORY"><Property name="PERIODIC_REPORT_TIME" value="240"/></Command></M2MXML>

Serial1 won't operate at 4800 baud

PROBLEM: Serial 1 won't operate at 4800 baud (it is actually operating at 1200 baud)

CAUSE: Incorrect entry on divisor table on current PSoC firmware.

SOLUTION: Reprogram PSoC firmware. Follow the directions on on the page 'How To: Reprogram PSoC'

SNAP Error Codes - What Do They Mean?

This file contains some descriptions of different error codes that may occur when using ish.

Mnemonic Value     Description
MMC_CMD0_FAILED -1     Reset MMC
MMC_CMD1_FAILED -2     Initialize MMC
MMC_CMD2_FAILED -3     Read CID (card identification register)
MMC_CMD3_FAILED -4     Set MMC address
MMC_CMD7_FAILED -8     Select MMC
MMC_CMD9_FAILED -10     Read CSD
MMC_CMD11_FAILED -12     Read data stream
MMC_CMD12_FAILED -13     Stop data transmission
MMC_CMD13_FAILED -14     Read Status register
MMC_CMD16_FAILED -17     Set block length
MMC_CMD17_FAILED -18     Read data block failed
MMC_CMD18_FAILED -19     Read multiple blocks
MMC_CMD20_FAILED -21     Write data stream
MMC_CMD24_FAILED -25     Write data block failed
ENO_FILE -30     No such file
ENO_MEM -31     Not enough memory
EBAD_FS -32     Unsupported file system (when mounting)
ENO_DEV -33     No such device
EDEV_USED -34     Device in use (when unmounting)
ENOT_IMPL -35     Functionality not implemented
EREAD_ERROR -36     Error reading
EWRITE_ERROR -37     Error writing
ERDONLY -38     File is opened as read only
EWRONLY -39     File is opened as write only
ENOT_OPEN -40     File not open
EBAD_FD -41     Bad file descriptor
ENOT_HIFS -42     Not HIFS file system
EDIR_END -43     End of directory reached
ENOT_DIR -44     Not a directory
ENOT_FILE -44     Not a file
EEOF -45     End of file reached
EEXISTS -46     File already exists
ENOT_SYMLINK -47     Not a symbolic link
ENOT_EMPTY -48     File/directory not empty
EISPIPE -49     File is a pipe
ENOT_FAT -50     File system isn't a FAT
EEOC -51     End of cluster chain
ENO_SPACE -52     No space left on device
EBAD_CHAIN -53     Bad cluster chain
EBAD_PATH -54     Bad path
EFILE_IN_USE -55     File already in use
EBAD_ARG -59     Bad argument to function
ENOTSUP -60     Functionality not supported
FLASH_COMPARE -61     Mismatch in comparing written and read back block
FLASH_RANGE -62     Flash block is out of range
FLASH_SECTOR_SIZE -63     Bad sector size of flash
MMC_BAD_CID -65     MMC CID information is bad
MMC_BAD_CSD -73     MMC CSD information is bad
MMC_NO_RESPONSE -89     No response from MMC
Status LEDs - What Do They Mean?
AVIDdirector Status LightsEach AVIDdirector-M2M has three LEDs: Radio, Application and Status. They are shown in that order left to right on the above photograph. The LEDs are used to show system operating status. There are two main modes of operation for the LEDs: Booting and running the M2MApplication Framework. Custom user written applications have full access to the LEDs and can override their behavior so this guide may not be applicable in these cases.

Each single LED consists of a combined Red and Green LED providing three unique colors: Red, Green and Amber (Yellow).

Running M2MApplication Framework

System: The system LED is used for a heartbeat and blinks on and off every two seconds. There is a low level system process that blinks this LED regardless if any other software is running on the device. With release 1.9 and later of the framework when the Framework is first loading it will blink Orange and when running it will blink Green; otherwise it will blink Red. This is tied into the M2M Application Framework's main loop so if it hangs or stops responding, the LED will revert back to Red from Orange or Green.

Application:
When the M2M Application Framework is starting this LED will blink Orange as various items are loaded (configuration file, drivers, default values). It will flash Green as each I/O device (e.g. GPS) is loaded and Red as each Radio is loaded. Note that it may pause Red for a period of time as the GPRS/CDMA/iDEN radios are loaded and initialized.

When the M2M Application Framework is running the LED is normally off. It will flash Green as each command is received from the portal and Red as data is sent to the Web Portal, and very briefly flash every second even with no activity. It flashes Orange if an error occurs. It flashes 1 to 6 times that corresponds to HTTP Error codes 100 to 600 (HTTP errors above 700 flash 6 times).

Radio: After the Radio is initialized this is set to Green when receiving data and Red when sending. For PPP Radios (e.g. Cellular, WiFi, XPORT) if the Data link is active (in Data mode) the LED is held at a constant Green with momentary Red flashes every 5 seconds. It will momentarily flash Orange for a Radio network error. For other radios or PPP radios that do not maintain the PPP link, this will normally be off unless data is received or sent.

AVIDdirector-M2M Booting

When the device is first booted the Application LED (middle) will first be Orange, Red and then Green. This corresponds to stages in the boot process and Green means the initial booting process is completed. If an error occurs during boot the System LED will blink Red a number of times that corresponds to the boot error. This document lists the error codes and their meaning. (AVIDdirector Error Code Documentation)

If the M2M Application Framework is loading, the System LED will blink Orange. The Application LED will brink Orange, and later Red and Green as various components are loaded.

Controlling the LEDs

The M2M_IO package provides methods to control the LEDs. This includes a background thread to blink an LED. The System LED is controlled by the Imsys Java processor and corresponds to the B5 or "Blinky" LED on the Imsys Technologies SNAP board. The Application and Radio LEDs are controlled by the Cypress PSoC processor.

Watchdog Timer

This FAQ contains a description of the WatchDog Timer introduced with release 1.6.0 and how it operates, monitors threads, and how a device driver or M2Mlet can be monitored with it.

What is a Watchdog Timer (WDT)?

A watch dog timer (WDT) is used to monitor mission critical aspects of a computer system and determine if the system is not operating correctly and take steps to put the computer back into a correct operating mode. A WDT is often used in embedded systems to ensure the system continues to operate correctly regardless of any system fault ,or if part of the hardware/software has stop working. A watchdog typically requires the various pieces it is monitoring to "check-in" or "pet the watch dog" at regular periods. If a program doesn't check in, the watch dog tries to restart the program or restart the computer system by starting from a known condition.

WDT and AvidDirector-M2M:

The Java processor and Imsys Technologies has an internal watch dog in the Java execution engine (or JVM) and if the system stops executing the Java opcodes, it will force a hardware reset of the system. This detects hardware problems or a bug in the JVM, but it doesn't often detect application problems (loops, block threads, or dead-lock conditions) since the JVM is executing correctly.

In release 1.6.0 and later of the AVIDirector Application Framework (M2MApp), a separate Watch Dog thread is added that monitors multiple threads in the M2MApp. If one of these threads stops responding, then it will log the thread which has stopped responding and reset the AVIDirector-M2M.

Using WDT in AvidDirector-M2M application:

The WatchDog timer is implemented in the class com.avidwireless.avidirector.WatchDogTimer, which is part of the ADM2MLib.jar file and whose source is located in
AVIDirector-Software/Adlibrary/source/com/avidwireless/avidirector/WatchDogTimer.java. It provides methods for a thread to register itself to be monitored, unregister itself and "pet" the watch dog (sorry for the "Pet" references but they are hard to resist when describing a WatchDog). Specifically the common methods are:

watchDogTimer.registerWatchDogMonitoredItem(this," ", 60000);  // start watching us and we will check in every 60 seconds (60000 ms)

watchDogTimer.resetWatchDogTimer(this);      // pet the watch dog - don't make her byte!
 
watchDogTimer.removeMonitoredItem(this);     // remove us from the list of threads to check

watchDogTimer.startMonitoringItem(this);     // start monitoring this again with the old period

watchDogTimer.startMonitoringItem(this, 60000);   // start monitoring this again checking every 60 seconds

watchDogTimer.stopMonitoringItem(this);           // stop checking up on us
   
Unless a thread registers itself with the watchdog, it is not monitored. Along with system threads, user written device drivers and M2Mlets can be registered with the WatchDog to be monitored.

How WDT works:

The WatchDogTimer is implemented as a separate Java thread that is started with a defined periodic interval for checking for dead thread. This is normally 60 seconds. The time period for the threads it monitors can be as long as required, but the WatchDog will check on them every 60 seconds. This period can be made shorter but then you have the risk of the watch dog's processing time will impact the overall available processor time. The WatchDogTimer is enabled by an entry in the M2MApp.ini file called "SYSTEM.WATCHDOG". The default is "true" to have the watch dog timer run. It can be disabled by setting this entry to "false". When initialized, the WatchDogTimer class first calls "SNAP.setWatchdogTimeout(period + MARGIN)". This enables the SNAP JVM to check that the method call "SNAP.feedWatchdog()" is called by the WatchDogTimer at least once each period time plus the MARGIN time. The MARGIN time is currently set to 30 seconds to prevent false watch dog resets. If the WatchDogTimer thread doesn't call "SNAP.feedWatchdog()", then a hardware reset of the AVIDirector is performed without a logging notification. This means that our system is really broken down and the WatchDogTimer cannot run. The system will spontaneously reboot itself.

The WatchDogTimer maintains a list (Java Hashtable) of threads it is monitoring. Each thread must implement the Java interface "WatchDogMonitoredClass" to identify that it will implement the WatchDogTimer contract. Each period, the WDT checks if the last time the WatchDogMonitoredClass thread checked in (by calling "resetWatchDogTimer) is greater than the contracted period set by "registerWatchDogMonitoredItem". If so, then the thread is deemed to have timed out and the WatchDogTimer calls the AVIDirectorApp.fatalError method, which writes an entry to the system Log (and turns on writing the Log to the file system if this is not enabled), writes a special entry to the file "/LastFatalError.log" and performs a hardware reset by calling "Ish.reboot". AVIDirectorApp.fatalError(int errorCode, String errorMessage) is used in multiple places whenever an object has detected a fatal error (e.g., a Radio class cannot establish a PPP connection 5 times in a row) and the Object wants to log a fatal error and reset the system.

A WatchDogMonitoredClass can permanently remove itself from the WDT's list by calling
watchDogTimer.removeMonitoredItem(WatchDogMonitoredClass this)
It will no longer be checked when it does this and it must call
registerWatchDogMonitoredItem(WatchDogMonitoredClass this,String name, int period)
to register itself again. This is done if a thread is terminating and if it is run again then a new thread instance is created. If a thread is running continuously in a loop but will be idle for an extended period of time, it can temporarily turn off the watch dog time from monitoring it by calling stopMonitoringItem(WatchDogMonitoredClass this)
The WDT will then ignore checking this class after this is called. The WatchDogMonitoredClass thread needs to call startMonitoringItem(WatchDogMonitoredClass this)
to return to being checked by the WDT. There is a version of this call with the time period (in milliseconds) that can be called if the thread wants to modify the time it is checked.

WDT in M2MAPP:

In M2MApp, the items that are monitored by WDT are:

  1. AVIDirectorApp - This is the main application thread for M2MApp. It handles the startup, normal operation, and shutdown of the system. When AVIDirectorApp starts, one of the first things it does is to create the WatchDogTimer instance with an internal polling time of 120 seconds. During the initial loading of classes, due to the time to read from the serial Flash memory chip and uncompress the Jar files, extra time is allowed for the watch dog timer. Once the AVIDirectorApp has completed initializing all the IODevices, Communicators and Radios, it sets the WatchDogTimer to a 60 second polling time. 

    The AVIDirectorApp performs a single continues loop consisting of:
    • Check for messages to send to the M2MXML Portal. If a messages exists, it will use the Communicator to send the messages. It adds the message to the Communicator's outbound queue and waits for an acknowledgment from the M2MXML portal. If a message is sent out, then the TXMessage timer is reset.
    • Check for incoming messages from the M2MXML portal. If it is waiting for an acknowledgment to a sent message that is checked and if present, the sent message is marked as being sent correctly and the next messages will be sent the next time the loop reaches (a). If it is not an acknowledgment but an error message (e.g. the device is not registered with the M2MXML portal), this is logged and the message is discarded. Otherwise, the packet is parsed to see if it contains a valid M2MXML message, and if so, it is then parsed and passed to the appropriate IODevice or M2Mlet. If a message is received, valid or not, the RXMessage timer is reset.
    • c. Check if the available memory is low and perform a garbage collection.

    If more than time specified by the M2MApp.ini M2MXML.MAX_NOCOMM_TIME parameter goes past with out a TX or RX message, then a fatal error is reported. The time specified is longest amount of time you will expect your application to be without communication to the M2MXML platform. 

    If the AVIDdirectorApp doesn't check in with the WatchDogTimer every 60 seconds, then the WDT will flag this set.

  2. Communicator. A Communicator is instantiated for each Radio class in the system. It performs the interface between the M2MXML packets, then calls the appropriate method for the radio to send and receive messages. When a message is sent, the Communicator ensures the Radio has sent the message correctly or tracks retry attempts by the Radio. Each Communicator has a queue of 25 outgoing and incoming messages. If this queue becomes full, then either the AVIDdirectorApp isn't handling the messages correctly or the Radio cannot send out the messages and a fatal Error condition is raised. This thread is monitored every 120 seconds to allow for a long retry time for a Radio. If the Radio doesn't respond, is hung, or the serial communication dies, then the Communicator thread won't update the WDT and will trigger a fault condition.
  3. Radio. Within the Radio, there may be threads that need to be monitored. Not all Radios require this. For example, in the AT_Radio_Modem class, the super class for all PPP type radios (GPRS, CDMA, iDEN, XPORT Ethernet), when the PPP link thread is alive it is monitored. When the PPP thread dies at the end of communication, then the thread is no longer monitored and removed from the list of monitored threads. Each Radio class also monitors its own state and will raise a Fatal Error when it cannot continue correctly. For example, if the AT_Radio_Modem class cannot establish a PPP link 5 times in a row, or the modem doesn't respond to commands, then the device is to be reset.
  4. IODevice. This handles all the internal I/O Devices on AVIDirector-M2M (TTL, HVC lines) and additional I/O devices (RFID, GPS, etc.). Each I/O device is suppose to perform its operation in a minimal amount of time, or it needs to start a thread to handle longer operations. The I/O Device drive will start to be monitored when it starts an I/O operation and stop monitoring when the I/O operation is complete. These operations should take less than a second, but a 60-second window is currently set to allow for longer I/O operations such as reading an RFID tag or acquiring a GPS lock.
What is M2MXML™?

M2MXML™is an XML language for machine to machine (M2M) data acquisition, command, and control. It is an open standard hosted at the Source Forge. The site describes the purpose of the specification: 

The purpose of the M2MXMLTM project is to develop an open-standard XML based protocol for Machine-To-Machine (M2M) communications. The primary design philosophy of M2MXMLTM is simplicity. Other attempts to develop protocols for M2M communications have resulted in protocols that are difficult to understand and too verbose to be used in small devices with limited communications bandwidth.
Currently, most M2M applications are a custom undertaking from end-to-end, including, in many cases, the development of custom communication protocols. One of the goals of M2MXMLTM is to establish an open-standard that can be adopted by device manufacturers and M2M application developers, thus allowing some interoperability that does not exist today.
The M2MXMLTM project will include the development of open-source APIs and code libraries to facilitate the use of the protocol by M2M application developers.

AVIDdirector supports the beta, 1.0, and 1.1 versions of the specifications, along with some additional enhancements such as "setConfiguration Bundles."

The current 1.1 M2MXML spec can be found here. (M2M XML Protocol Documentation)

Serialport Mappings

Mapping the serial port allows you to create a software mapping between an actual hardware connection of a device such a GPS to the serial ports on the PSoC chip on AVIDdirector . This is one of the features that makes AVIDdirector extremely flexible in the following ways:

  1. It allows AVIDdirector to make software connections with various mounted devices without making any hardware changes. 
  2. Due to a software based serialport mapping, AVIDdirector can communicate with a device irrespective of where it is physically mounted on the AVIDdirector . (unless it has specific needs)

AVIDdirectors have various hardware locations where a device could be physically mounted (Radio, Radio2, Radio3, RS232, Radio_A, Radio_B etc.). There are only 4 that can be mapped at any given time to the 4 serialports (serial1, serial2, serial3, serial4). 

To See all the possible serialports are radios on your AVIDdirector type in 'mapserialport' at the root prompt. This should also give you the current serialport mappings.

/root > mapserialport
Usage: MapSerialPort serialN Port [-hw|-no|][-o] where N is 0..4, Port is one of CONSOLE, RJ12/TTL2021, RS232, RADIO, EXTA, RADIO2, RADIO3, RS232_2, EXTB, TTL910, TTL1112, TTL1314, TTL1617 or DISCONNECT
-hw is optional to enable hardware handshaking
-no disables hardware handshaking lines
-o turns power on the Radio Board
serial0 mapped to device CONSOLE
serial1 mapped to device RS232
serial2 mapped to device TTL2021
serial3 mapped to device RADIO_A
/root >

As seen in the example above serial0 is usually mapped to CONSOLE and used for Snapdev. serial0 can be mapped to any of the hardware ports but this could render Snapdev (console) inaccessible. Provisions should be made before mapping serial0 to hardware port other than CONSOLE.

You can map serial port serial1 to hardware port radio2 and turn on the radio board with the '-o' option, as below:

/root > mapserialport serial1 radio2 -o
serial1 mapped to device RADIO2
Radio Power ON
/root >

SnapDev Firmware bootloader does not respond

AVIDdirector-M2M has a bootloader mode used to reprogram the device's Imsys Java firmware. Bootloader mode is entered by pressing Reset or F5 in SnapDev. It is important the correct bootloader file is loaded.

To Enter Bootloader mode:

Normally when you press F5 or select File | Reset from the Menu you should see "Resetting" on the bottom of the SnapDev screen and then "Loading" as the bootloader software is loaded. The bootloader software is located in a file snap_loader3.gpx and if you are using the standard Imsys Technologies software installation, SnapDev will try to load using SNAP module bootloader's snap_loader3.gpx instead of the AVIDdirector-M2M snap_loader3.gpx.

To fix this, copy SNAPDev_Files\snap_loader3.gpx from the AVIDdirector-M2M installation directory to the bin directory in the AVIDdirector-M2M software release, or the bin directory in the Imsys Technologies release. Try entering bootloader mode again.

When you have successfully entered firmware loader mode you will see a display like:

SNAP loader v 0.1.10 (Build date: Aug 19 2005 19:40:48)
$

Why does my program not run on AVIDirector-M2M?

Trouble shooting steps for writing a custom Java program or M2MLet on AVIDirector-M2M.

When a program on AVIDdirector-M2M immediately returns it is usually an indication of a class loading problem. This is caused mainly by one of the following list of problems:

  1. One or more of the class files have not been preverified. If you run java with the -v for verbose, you will see a line like:
  2. [Verifier] Error verifying class 'ThreadTest', result: Target bad type (8). It is a known feature request to print this error when the program is run without a verbose option.
  3. The program was compiled without the '-target 1.1' option. This will give a variety of errors, such as 'illegal constant pool'. The target 1.1 ensure the class file is in the format used by Java 1.3 and earlier and is required for the preverify.
  4. During compile the bootclasspath wasn't set to point at the snap_rt.jar file. There are differences in constant values between the Imsys J2ME and other J2ME and J2SE systems (the javax.comm.Serial used to have that problem). It is important to note that you need to compile your programs against the snap_rt.jar file AVIDWireless provides on the CD and NOT the snap.jar file in the Imsys releases. We have done changes for the hardware differences and also fixed some of the constant differences to be more compatible with J2ME/J2SE.
  5. Below is a sample build file:
    @echo off
    REM Source files
    set SNAP=D:\AVIDirector-M2M\SNAP
    set SRC= ThreadTest.java
    javac -target 1.1 -bootclasspath %SNAP%\classes -classpath . %SRC%
    mkdir output
    %SNAP%\bin\preverify -classpath %SNAP%\classes -nofinalize -d output .
    REM move output\*.class .
    REM rmdir /s /q output
    pause
  6. Finally make sure the libraries (ADM2Mlib.jar, M2MApp.jar, dalsemi.jar & snap_rt.jar) on the AVIDdirector are the same version & build as the one on your development system. If not update the older versions to the latest versions from the distribution page from this Google group.

space

Home space Products space Demos space Specs space Support space Contactsspace Pressspace Policyspace Papers

Numerex © 2015. A US space technology company.

Address:
8144 Walnut Hill Lane
Suite 310
Dallas, TX 75231
770.615.1394