mch/README

   1 1) class MoteHost
   2
   3 The class containing main function. It tries to connect to Re-Mote server and
   4 then begins with serviceLoop(). It creates pipe(/var/run/motehost.events) for
   5 signaling the events (PLUG & UNPLUG) of each mote. The events are handled by
   6 UDEV system allowing to register programs which then run when certain event
   7 occurs.
   8
   9 For TMote:
  10 BUS={usb}, SYSFS{idVendor}=="0403", SYSFS{idProduct}=="6001" RUN+="plugpiper motehost.events"
  11
  12 For Micaz:
  13 BUS={usb}, SYSFS{idVendor}=="0403", SYSFS{idProduct}=="6010" RUN+="plugpiper motehost.events"
  14
  15 The program plugpiper writes single char into the pipe as a notification for
  16 the service loop. In more details, the funtion select() monitors all registered
  17 file descriptors until any of them becomes ready (write, read operation on
  18 the destriptor) and then accomplishes the particular service.
  19
  20 The second step is to create list of the motes currently available in Re-Mote.
  21 It's handled by the funtion DeviceManager::refresh(). I'll discuss that in the
  22 particular class.
  23
  24 The third step is to build set of descriptors which will be monitoring by
  25 select() function within the service loop.
  26
  27 The service loop is based on the function select() as I mentioned earlier.
  28 The specific function(handleMessage(), handlePlugEvent(), handleMote())
  29 is invoked according to the activity on the certain descriptor.
  30
  31 -handleMessage()
  32 It indicates that the message from Re-Mote server was received and tries to
  33 find out the type of the message. There are two types possible (reguest
  34 & data). If it's request then the function handleRequest() will be called.
  35 The data are handled by mote->writeBuf().
  36
  37 --handleRequest()
  38 The commands from Re-Mote server: program, cancelProgramming, status, reset,
  39 start & stop
  40
  41 I won't disscus the commands here since they relate to Mote class.
  42
  43 -handlePlugEvent()
  44 It indicates that the change happened on the descriptor relating to the file
  45 motehost.events. The function has to recreate(DeviceManager::refresh())
  46 list of the motes and notify the Re-Mote server about the availability of the
  47 motes (PLUG_MOTES & UNPLUG_MOTES).
  48
  49 -handleMoteData()
  50 It checks data coming from the mote and if so, the function sends them
  51 directly to the Re-Mote server. If there are no data from the mote
  52 (the function p_mote->readBuf() is called once) then it checks if the
  53 mote programming happens and reports it back to the Re-Mote server in
  54 case of that the programming status was successful (done).
  55
  56 Question: synchronization between readBuf() & getProgrammingResult within
  57           the context of handleMoteData(). When does it reports that the
  58           programming is done?
  59
  60 ---------------------------------------
  61
  62 I would say that there is no need to change this class regarding support
  63 for TMote & MicaZ. Perhaps, just small change(rename the file) within the
  64 function program().
  65
  66 2) class DeviceManager
  67
  68 The class managing the motes. It keeps the track of the motes which are
  69 currently available for the Re-Mote server. It also maintains the motes
  70 recently being added or removed.
  71
  72 -refresh()
  73 The function is public and serve as an interface for updating the list of
  74 the motes currently in the system.
  75
  76 -readUsbDevices()
  77 The function reads and parses the data from the system file specified by
  78 usbdevicePath (/proc/bus/usb/devices). The data are stored using the
  79 usbdevice_t structure (devNo, bus, parent, port, serial). The two devices
  80 arrays are maintained by the function. The first one is devicesById and
  81 saves the devices ordered by SerialNumber (serial inside of usbdevice_t).
  82 The second one is devicesByConnection and saves the same set of devices,
  83 but ordered by the key (calculated by the function get_device_key()).
  84
  85 --get_device_key()
  86 The key is created based on the values inside of usbdevice_t (bus, parent,
  87 port).
  88
  89 -readMoteDevices()
  90 The function takes care of the three motes arrays (motes, motesNew, motesLost).
  91 The information is taken from the system file specified by usbserialPath
  92 (/proc/tty/driver/usbserial, root is allowed to read the file). The function
  93 tries to match the information (tty, hcid, ports, path) with the data stored
  94 in the usbdevice_t structure in order to calculate MAC address for the motes
  95 (based on SerialNumber). The mote objects are then created by new Mote(mac,
  96 path, tty) and the motes, motesNew, motesLost objects are updated accordingly.
  97
  98 Needs to be clarified:
  99 -devicesById.find(hcid); //suppose hcid=6001 resp. 6010 (have to run it separately)
 100 -findUsbDevice();
 101
 102 ---------------------------------------
 103
 104 Generally speaking, the system should be able to recognize different types of
 105 motes (DIG528-2, TMote, MicaZ, ...) and then handle communication with the
 106 motes according that. As a example, the MIB520 board has two serial ports,
 107 one of them for the programming and the second one for the communication
 108 with MicaZ.
 109
 110 3) class Configuration
 111 The class parses the configuration file remote-mch.cfg and stores the values
 112 into the buffer. The configuration file should reflect multi-platforms system.
 113 (DIG528-2, TMote, MicaZ, ...).
 114
 115 4) class Mote
 116 The class defines the mote object and inherits the class SerialControl. It's
 117 quite straightforward and uses parameters mac, path, ttyNum for creating the
 118 mote object.
 119
 120 I think we could consider extending the object constructor to:
 121 Mote::Mote(type, mac, path, tty). Where the parameter type would be the type
 122 of mote (DIG528-2, TMote, MicaZ, ...). Opened to discussion.
 123
 124 QUESTION: Why do you make testmote in the function validate()?
 125
 126 5) class SerialControl
 127 The class supporting communication (commands, data) with the motes. The object
 128 is created during creation of the mote object and parameter portnumber is passed
 129 to the constructor.
 130
 131 -openTty()
 132 It handles opening and setting the serial port (ttyUSB+portnumber). The state
 133 of the serial port is indicated by variable isOpen. The mote itself is put in
 134 to stop mode (keep reseting).
 135
 136 -closeTty()
 137 It closes the serial port and restore old setting.
 138
 139 -program()
 140 The function handles flash programming of the mote. The MAC address is used
 141 for programming. The bash command for flash programming (msp430-bsl, uisp)
 142 is put together to be able run as a separate process (child) connected with
 143 parent process by a pipe. Once the programming is finished, the child process
 144 writes the programming status into the pipe. The function rebuildFdSet() is
 145 called every time when the function select() is activated and it allows to
 146 get the notification even on the pipe descriptor. The data is read from the
 147 pipe by the function readBuf(). The child process then closes pipe's descriptors
 148 and on this event the function readBuf() gets readlen <= 0 and reports the
 149 status of the mote programming.
 150
 151 QUESTION:
 152 Not sure about the story above. When does it rebuildFdSet() for pipe
 153 descriptor? The port is closed by _close() so the descriptor is no longer
 154 valid.
 155
 156 -readBuf()
 157 The function reads data from either serial port or the pipe. It also checks
 158 if the programming is in progress and if so, it waits until the child process
 159 is finished and reports the status.
 160
 161 -cleanUpProgram()
 162 It closes the pipe descriptor and opens new connection to the mote. The
 163 variables isProgramming and wasProgramming are set to false and true. The
 164 buffer containing the image is delated.
 165
 166 -getProgrammingStatus()
 167 It returns the value of the variable wasProgramming and after that it sets
 168 the variable to false.
 169
 170 -cancelProgramming()
 171 It checks if the programming is active and if so, it kills the child process
 172 and reopen tha connection to the mote.
 173
 174 -getFd()
 175 It returns the port for the function rebuildFdSet().
 176
 177 -getStatus()
 178 It reports back the mote status (PROGRAMMING, UNAVAILABLE, RUNNING, STOPPED).
 179
 180 -start(), stop()
 181 These functions are platform dependent and needs to be changed for particular
 182 platform (DIG528-2, TMote, MicaZ, ...).
 183
 184 -reset()
 185 It uses the functions stop() & start().
 186
 187 ---------------------------------------
 188
 189 The functions which needs to be changed:
 190 _open() ... rate B38400
 191 program() ... bash command
 192 stop()
 193 start()