AdaRail on Droid
Java Documentation:
Throttle:
A class which represents a throttle for a Digitrax train set.
It asynchronously sends and receives messages to the Digitrax system. Throws base throttle
events which contain a message about what happened and an enumerated type which
represents the event opcode.
How to use –
Import the throttle library and instantiate a new throttle object. Once the object is
instantiated you can call the throttles connect method to connect to a Digitrax system. If
connect returns false there was an error in the connection. There is a seven second timeout on
connection so that if there is no connection after that time it will return false.
By design all object methods return true if they worked or false if they failed. This
minimized exceptions from the throttle. Information returned from Digitrax is placed into
events. Custom events can be passed in to the throttle via base event handler interface. The
event interface allows for the custom handling of Digitrax messages and opcodes. The throttle
has a hash table of trains indexed by their physical address. This is used to look up train status.
After connecting you can call the methods provided which will do the specified task.
controlTrain: Takes in a physical train address and attempts to allow the throttle to
control it. Digitrax system should return this call with an OPC_SL_RD_DATA message
which contains the slot number of the controlled train.
setTrainSpeed: sets a controlled train’s speed to an amount. This takes in a slot
(returned by calling control train) and a speed (1-127).
setSwitchState: sets a switch to thrown or closed. Input is the switch number followed
by the state (0 is closed, 1 is thrown)
setLight: sets whether the light for a controlled train is on or not. Input is the slot
number of the train followed by a Boolean if the light is on or not.
setHorn: sets whether the Horn for a controlled train is on or not. Input is the slot
number of the train followed by a Boolean if the light is on or not.
setBell: sets whether the Bell for a controlled train is on or not. Input is the slot number
of the train followed by a Boolean if the light is on or not.
setMute: sets whether the sound for a controlled train is on or not. Input is the slot
number of the train followed by a Boolean if the light is on or not.
stopAll: sets the speed of all trains to be 1 (the abrupt stop in the Digitrax train set).
JavaRail:
This is a library of methods for the throttle to call.
This contains all the methods for forming messages that interact with the Digitrax train set. It
also decrypts messages that the Digitrax sends out. All methods besides decrypt and checkSum
return a byte array; checkSum returns a single byte and decrypt returns an event.
makeControlTrain: takes in a physical address for a train and returns an array of bytes
which when sent will ask for a slot for that train (OPC_LOCO_ADR is sent and
OPC_SL_RD_DATA is received)
makeSetSpeed: returns an array of bytes which when sent will set the speed of a
controlled train to something. Inputs are slot number and speed (0-127)
checkSum: takes in an array of bytes and returns the result of an XOR operation
performed on 'FF' and indexes 2 through the length of the array minus 1 and returns this
value. For use by the other methods in JavaRail.
makeChangeSwitch: takes in a switch number and a Boolean for what state that switch
is in. If true returns an array of bytes which when sent will throw a switch. If false
returns an array of bytes which when sent will close a switch.
makeSetMisc: Takes in a slot and four Boolean values. These Boolean values represent
the direction of the train (true = backwards, false = forwards), and whether the horn,
bell, and lights are on or off (in that order). It returns an array of bytes which when sent
sets all of these settings.
decode: takes in one message sent from Digitrax and translates it into something that is
useful for the throttle. It returns a base event which describes what the message was
and information about what that message contained.
-switch report: returns which switch was changed and the current state
-switch request: returns which switch is requested to be changed and the state
-OPC_LONG_ACK: returns a message saying there are no slots left
-Slot report: returns whether or not this was requested, if it was it returns the
slot of the train and information about that train's state (bell, lights,....)
-Set Speed: returns a message saying another throttle is setting a certain slots
speed to some number
-set dirf: returns information about what the miscellaneous states are (bell,
lights, horn direction)
-set sound: returns that another throttle is attempting to mute or unmute a
train
-input report: says a sensor fired and which one
-*putswitchstate: returns information about a switch (which one and state)
-*puttraininfo: gives all information about a train
-*puttrainstate: gives information about whether or not a train is moving
-*puttrainpos: gives the sensors for which a train is between
-defaults to returning the opcode of the message if it doesn't recognize the
message
*Messages have not been tested.
How to install on an android tablet:
Download or get the railDroid1.*.apk from the final zip. Install an APK installer on your android device.
Next go to settings in your android device and the go to the applications tab. Next click the “Unknown
sources” check box. Once you do this go to you APK install that you installed though the android market,
select the APK file and then install. RailDroid should now be installed.
The Android side of this project is mostly just a wrapper for the JavaRail/Throttle code. I am not really
sure what documentation to provide other than some how-to use it. Computationally there is nothing to
exciting going on here, most of the Android time was spent learning how the MVC system for android
works. Here are some how to’s and screen shots. All the shots are from an Android 3.2(Honeycomb)
emulator.
Here is the initial screen. The address refers to IP address of the trainset. The port is the port of the train
server. Below the connection button on the left is an indicator of whether or not the throttle has
connected to the rail road.
This is the railroad switch layout. The little switch buttons are touchable and will send a message to the
railroad to close or open a switch.
Here is a picture of the switch layout with a few opened and closed. Below is a message saying the
switch message was sent successfully.
This is the train control screen. This screen allows you to send messages to the railroad in order to
control your trains. Under the Set Train button there is some text to notify weather or not you are
currently controlling a train. This is dynamic and checks against all trains registered on the throttle.
Here is an example of a connected train. Notice the train address in the train address bar. If the number
in the bar is changed then the connection notification will check the current number against all
registered train. For example, if I register train 1111 then 2222 if I type in 1111 it will show up as
connected as will 2222 but 111,222,1212,1… will all show up as Not connected.
Here is an example of an empty log. Once the log fills up sliding the text up and down will cause it to
scroll. There is a bug with the sensor firing logs, the read as 4, I am mostly positive this is coming from
the simulator though. I debugged then watch the simulator with the Wireshark network monitoring tool.
The simulator is definitely sending 4 identical packets. Included with this document is a Wireshark
printout documenting the packet conversation.