comment updates

diff --git a/apps/AntiTheft/README.txt b/apps/AntiTheft/README.txt
index 676a90c3e610915c4fc2815237b89462722da65a..b1788821575ebcfa2158f473617520c6bbbe767a 100644 (file)
--- a/apps/AntiTheft/README.txt
+++ b/apps/AntiTheft/README.txt
@@ -38,9 +38,28 @@ forwarding theft alerts from the sensor network to the PC.
 Tools:
 
 The java directory contains a control GUI for the antitheft demo app.
+To run it, change to the java subdirectory and type:
+  make # Unecessary if antitheft.jar exists
+  java net.tinyos.sf.SerialForwarder -comm serial@<serial port>:<mote>
+  # e.g., java net.tinyps.sf.SerialForwarder -comm serial@/dev/ttyUSB0:mica2
+  # or java net.tinyps.sf.SerialForwarder -comm serial@COM2:telosb
+  ./run
+
+The buttons and text field on the right allow you to change the theft detection
+and reporting settings. The interval text box changes the interval at which
+motes check for theft (default is every second). Changes are only sent to the
+mote network when you press the Update button. Finally, if you've selected
+the Server theft report option, the message area will report received theft
+messages.
 
 Known bugs/limitations:
 
+- A newly turned on mote may not send theft reports (when the "Server"
+  theft report option is chosen), as:
+  o It takes a little while after motes turn on for them to join the multihop
+    collection network. 
+  o It can take a little while for motes to receive the current settings.
+
 None.
 
 

diff --git a/apps/AntiTheft/java/AntiTheftGui.java b/apps/AntiTheft/java/AntiTheftGui.java
index 83db2bf7c029c70edf9c2ec61cbf7f0fdd7cb62a..a1e8c04c678500bbb1ee2ece6cb3a005e656f2a4 100644 (file)
--- a/apps/AntiTheft/java/AntiTheftGui.java
+++ b/apps/AntiTheft/java/AntiTheftGui.java
@@ -47,16 +47,22 @@ import net.tinyos.packet.*;
 import net.tinyos.util.*;
 
 public class AntiTheftGui implements MessageListener, Messenger {
-    MoteIF mote;
-    JFrame frame;
-    JTextArea mssgArea;
-    JTextField fieldInterval;
+    MoteIF mote;               // For talking to the antitheft root node
+
+    /* Various swing components we need to use after initialisation */
+    JFrame frame;              // The whole frame
+    JTextArea mssgArea;                // The message area
+    JTextField fieldInterval;  // The requested check interval
+
+    /* The checkboxes for the requested settings */
     JCheckBox detDarkCb, detAccelCb, repLedCb, repSirenCb, repServerCb,
        repNeighboursCb;
 
     public AntiTheftGui() {
        try {
            guiInit();
+           /* Setup communication with the mote and request a messageReceived
+              callback when an AlertMsg is received */
            mote = new MoteIF(this);
            mote.registerListener(new AlertMsg(), this);
        }
@@ -66,11 +72,14 @@ public class AntiTheftGui implements MessageListener, Messenger {
        }
     }
 
+    /* Build up the GUI using Swing magic. Nothing very exciting here - the
+       BagPanel class makes the code a bit cleaner/easier to read. */
     private void guiInit() throws Exception {
        JPanel mainPanel = new JPanel(new BorderLayout());
        mainPanel.setMinimumSize(new Dimension(500, 250));
        mainPanel.setPreferredSize(new Dimension(500, 300));
 
+       /* The message area */
        JScrollPane mssgPanel = new JScrollPane();
        mssgPanel.setVerticalScrollBarPolicy(JScrollPane.VERTICAL_SCROLLBAR_ALWAYS);
        mssgPanel.setAutoscrolls(true);
@@ -79,6 +88,7 @@ public class AntiTheftGui implements MessageListener, Messenger {
        mainPanel.add(mssgPanel, BorderLayout.CENTER);
        mssgPanel.getViewport().add(mssgArea, null);
        
+       /* The button area */
        BagPanel buttonPanel = new BagPanel();
        GridBagConstraints c = buttonPanel.c;
 
@@ -108,7 +118,6 @@ public class AntiTheftGui implements MessageListener, Messenger {
        fieldInterval = buttonPanel.makeTextField(10, null);
        fieldInterval.setText(Integer.toString(Constants.DEFAULT_CHECK_INTERVAL));
 
-       // Send settings button
        ActionListener settingsAction = new ActionListener() {
                public void actionPerformed(ActionEvent e) {
                    updateSettings();
@@ -118,7 +127,7 @@ public class AntiTheftGui implements MessageListener, Messenger {
 
        mainPanel.add(buttonPanel, BorderLayout.EAST);
 
-       // The frame part
+       /* The frame part */
        frame = new JFrame("AntiTheft");
        frame.setSize(mainPanel.getPreferredSize());
        frame.getContentPane().add(mainPanel);
@@ -128,18 +137,29 @@ public class AntiTheftGui implements MessageListener, Messenger {
            });
     }
 
+    /* Add a message to the message area, auto-scroll to end */
+    public synchronized void message(String s) {
+       mssgArea.append(s + "\n");
+       mssgArea.setCaretPosition(mssgArea.getDocument().getLength());
+    }
+
+    /* Popup an error message */
     void error(String msg) {
        JOptionPane.showMessageDialog(frame, msg, "Error",
                                      JOptionPane.ERROR_MESSAGE);
     }
 
+    /* User pressed the "Update" button. Read the GUI fields and
+       send a SettingsMsg with the requested values. When the
+       requested settings are bad, we silently update them to sane
+       values. */
     public void updateSettings() { 
        SettingsMsg smsg = new SettingsMsg();
        short alert = 0;
        short detect = 0;
        int checkInterval = Constants.DEFAULT_CHECK_INTERVAL;
 
-       /* Extract current interval value, ignoring bad values */
+       /* Extract current interval value, fixing bad values */
        String intervalS = fieldInterval.getText().trim();
        try {
            int newInterval = Integer.parseInt(intervalS);
@@ -151,6 +171,7 @@ public class AntiTheftGui implements MessageListener, Messenger {
            fieldInterval.setText("" + checkInterval);
        }
 
+       /* Extract alert settings */
        if (repLedCb.isSelected())
            alert |= Constants.ALERT_LEDS;
        if (repSirenCb.isSelected())
@@ -165,6 +186,7 @@ public class AntiTheftGui implements MessageListener, Messenger {
            repLedCb.setSelected(true);
        }
 
+       /* Extract detection settings */
        if (detDarkCb.isSelected())
            detect |= Constants.DETECT_DARK;
        if (detAccelCb.isSelected())
@@ -175,10 +197,10 @@ public class AntiTheftGui implements MessageListener, Messenger {
            detDarkCb.setSelected(true);
        }
 
+       /* Build and send settings message */
        smsg.set_alert(alert);
        smsg.set_detect(detect);
        smsg.set_checkInterval(checkInterval);
-
        try {
            mote.send(MoteIF.TOS_BCAST_ADDR, smsg);
        }
@@ -187,21 +209,17 @@ public class AntiTheftGui implements MessageListener, Messenger {
        }
     }
 
-    public static void main(String[] args) {
-       AntiTheftGui me = new AntiTheftGui();
-    }
-
-    synchronized public void messageReceived(int dest_addr, Message msg) {
+    /* Message received from mote network. Update message area if it's
+       a theft message. */
+    public void messageReceived(int dest_addr, Message msg) {
        if (msg instanceof AlertMsg) {
            AlertMsg alertMsg = (AlertMsg)msg;
-
-           String warning = "Theft of " + alertMsg.get_stolenId() + "\n";
-           mssgArea.append(warning);
-           mssgArea.setCaretPosition(mssgArea.getDocument().getLength());
+           message("Theft of " + alertMsg.get_stolenId());
        }
     }
 
-    public void message(String s) {
-       error(s);
+    /* Just start the app... */
+    public static void main(String[] args) {
+       AntiTheftGui me = new AntiTheftGui();
     }
 }

diff --git a/apps/AntiTheft/java/BagPanel.java b/apps/AntiTheft/java/BagPanel.java
index 20e340a372fabf10ce2bafa666134565b5b61d1f..4e2e3fe0b9bbd3bfc29da4a75951554f2124a115 100644 (file)
--- a/apps/AntiTheft/java/BagPanel.java
+++ b/apps/AntiTheft/java/BagPanel.java
@@ -29,12 +29,19 @@ public class BagPanel extends JPanel {
     GridBagLayout bag;
     GridBagConstraints c;
 
+    /* Create a panel with a bag layout. Create some constraints are
+       users can modify prior to creating widgets - the current constraints
+       will be applied to all widgets created with makeXXX */
     public BagPanel() {
        bag = new GridBagLayout();
        setLayout(bag);
        c = new GridBagConstraints();
     }
 
+    /* The makeXXX methods create XXX widgets, apply the current constraints
+       to them, and add them to this panel. The widget is returned in case
+       the creator needs to hang on to it. */
+
     public JButton makeButton(String label, ActionListener action) {
        JButton button = new JButton();
         button.setText(label);
@@ -71,10 +78,11 @@ public class BagPanel extends JPanel {
        return tf;
     }
 
-    public void addSeparator(int axis) {
+    public JSeparator makeSeparator(int axis) {
        JSeparator sep = new JSeparator(axis);
        bag.setConstraints(sep, c);
        add(sep);
+       return sep;
     }
 
 }