# TinyOS Communications.txt
# 7/15/2004
# Tips/Notes on how to use the java communication interfaces in TinyOS-1.1


NOTE: Rob Szewcyzk has committed code (5/31/2004) that changes how TOSMsg 
      works.  Now it cannot be instantiated directly, but only through 
      MessageFactory.createTOSMesssage.
	Run 'cvs log MessageFactory.java' in the
      tinyos-1.x/tools/java/net/tinyos/message directory for more details.
	The notes below are for the cvs tree prior to 5/31/2004.


Most of the communication java files reside in the packages:
************************************************************
net.tinyos.message
	Interface: MessageListener
	Message Types: TOSMsg, builds on java classes BaseTOSMsg & Message
	Tools:  MessageInjector, MessagePanel, etc.
	Other: Receiver, Sender, MoteIF
net.tinyos.packet
	Sources: PhoenixSource builds on other PacketSources NetworkByteSource,
	         SerialByteSource, SFSource, etc.
	Interface: PacketListenerIF
	Other: BuildSource, Packetizer, PacketSource (java interface)
net.tinyos.sf
	SerialForwarder and old.SerialForward
net.tinyos.mcenter
	Message Center
net.tinyos.tools
	Basic tools: BcastInject, SimpleCmd, ListenRaw, etc.
net.tinyos.util
	Messenger (for printing status messages of the source)



Typical Call Chains:
********************
Receive
-------
-0-> Source -1-> Receiver -2-> Listener
Interface -0-> depends on the source type.  can be from SerialForwarder
Interface -1-> is of type PacketListenerIF
Interface -2-> is of type MessageListener

ex. NetworkByteSource(run by PhoenixSource Thread) -> SFClient (the receiver)
    -> Socket at server port (opened in SFSource, reading and writing in 
    SFProtocol) -> SFSource -> Receiver -> Listener

Receive Diagnostics
-------------------
Source -a-> Messenger
-a-> is a Messenger Interface

Send
----
Sender -> Source 
* MoteIF registers listeners with the standard Receiver.java
  and sends messages through the standard Sender.java
* Setting up the receive call chain
  ~ note that the messenger is passed into the source during source creation
    (<-) but the source and others are passed/registered in the -> direction



GroupID filtering
*****************
GroupIDs are supposed to be handled by the mote serving as the basestation
	 (TransparentBase does not filter for GroupIDs, TOSBase does)
GroupIDs are filtered in the receiver (deprecated, not used by PhoenixSource)
GroupIDs are tagged in the sender (defaults to 0x7d in Sender.java)



SerialForwarder
***************
All communications on the computer side wants to connect to the server port
by opening a socket to it.  This is the 'sf@localhost:9001' often opened by
sources.  Multiple clients can connect to the server port.

The connection used to connect to the mote is determined by the '-comm'
option, which is reflected (and can be changed) on the SerialForwarder window
under the box "Mote Communications".



TOSMsg
******
Message<-BaseMsg<-TOSMsg
<- means inherits from

* use Message.dataGet() and Message.dataSet() to modify Msg
  ~ probably should NOT use TOSMsg.get_data() since it uses 
    TOSMsg.numElements_data().  The comments of Sender.send() and
    Receiver.packetReceived() implies does not work correctly since the
    new packetSource format does not use the crc field.
* use BaseTOSMsg.set_length() to change the length field in the packet
* use BaseTOSMsg.get_length() to get the length field in the packet
  ~ Message.data_length is just an extra field in TOSMsg, and not part of
    the byte array representing the actual packet.  Doesn't seem
    to be used much, except for Message.checkBounds(), which is used by
    Message.getUIntElement() and Message.setUIntElement().
* Actual packet size must match Allocated Packet Size to be sent
  (this is  checked in AbstractSource.check(packet) )
  ~ Allocated packet size = size of the TOSMsg during instantiation, 
    which is the size of the byte array returned by Message.dataGet()
  ~ Actual Packet Size = length stored in the length field of the packet +
    the data offset



Commands
********
* Use "BuildSource" to build a source... don't instantiate the sources
  directly.
* If you choose not to use MoteIF, you must create your own receiver/sender
  explicitly.  
* Programmer writes the Listener java files and instantiates messages 
  inheriting from TOSMsg for sending.