added helper tool description

.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+
+
+

LedBlinkerHelperTool/LedFlasher.ino

@@ -0,0 +1,166 @@
+//============================================================================
+// Filename: SparsnasLedBlinker.ino
+// Purpose:  Provide a configurable led blinking pulse as a help for decoding
+//           the transmitted packet data.
+//============================================================================
+
+//----------------------------------------------------------------------------
+//------------------------------- Include Files ------------------------------
+//----------------------------------------------------------------------------
+#include <Button.h>
+#include <Wire.h> 
+#include <RtcDS3231.h>
+#include "U8glib.h"
+
+//----------------------------------------------------------------------------
+//----------------------------- Global variables -----------------------------
+//----------------------------------------------------------------------------
+Button                IncButton(7);
+Button                DecButton(8);
+U8GLIB_SSD1306_128X64 oled(U8G_I2C_OPT_NONE);
+RtcDS3231<TwoWire>    rtcObject(Wire);
+
+const byte            wakePin     = 2;
+const byte            ledPin      = 3;
+
+byte                  hours       = 0;
+byte                  minutes     = 0;
+byte                  seconds     = 0;
+byte                  blinkDelay  = 1;
+byte                  secondCnt   = 0;
+volatile bool         alarmFlag   = false;
+
+//----------------------------------------------------------------------------
+// updateTime
+//----------------------------------------------------------------------------
+void updateTime()
+{
+  RtcDateTime now = rtcObject.GetDateTime();
+  hours = now.Hour();
+  minutes = now.Minute();
+  seconds = now.Second();
+}
+
+//----------------------------------------------------------------------------
+// updateDisplay
+//----------------------------------------------------------------------------
+void updateDisplay()
+{
+  char timeString[32];
+
+  oled.setFont(u8g_font_helvB10);
+
+  sprintf(timeString, "Time: %02u:%02u:%02u", hours, minutes, seconds);
+  oled.setPrintPos(0, 20);
+  oled.print(timeString);
+
+  sprintf(timeString, "BlinkDelay: %u", blinkDelay);
+  oled.setPrintPos(0, 45);
+  oled.print(timeString);
+}
+
+//----------------------------------------------------------------------------
+// handleRtcAlarm
+//----------------------------------------------------------------------------
+void handleRtcAlarm() 
+{
+  alarmFlag = false;
+  rtcObject.LatchAlarmsTriggeredFlags();
+
+  secondCnt++;
+  if (blinkDelay == 0) {
+    secondCnt = 0;
+  }
+
+  if (blinkDelay > 0)
+  {
+    if (secondCnt == blinkDelay)
+    {
+      secondCnt = 0;
+      digitalWrite(ledPin, HIGH);    // flash the led
+      delay(100);                    // wait a little bit
+      digitalWrite(ledPin, LOW);     // turn off led  
+    }
+  }
+}
+
+//----------------------------------------------------------------------------
+// handleInterrupt
+//----------------------------------------------------------------------------
+void handleInterrupt() 
+{
+  // Try to do as little as possible in this ISR
+  alarmFlag = true;
+}
+
+//----------------------------------------------------------------------------
+// setup
+//----------------------------------------------------------------------------
+void setup() 
+{
+  // Initialize global variables
+  blinkDelay = 1;
+  secondCnt = 0;
+
+  // Initialize push buttons
+  IncButton.begin();
+  DecButton.begin();
+
+  // Initialize pins
+  pinMode(ledPin, OUTPUT); // 
+  pinMode(wakePin, INPUT); // 
+  // Initialize the RTC and the alarm associated with it.
+  DS3231AlarmOne alarm1(0,0,0,0,DS3231AlarmOneControl_OncePerSecond);
+  rtcObject.Begin();
+  if (!rtcObject.GetIsRunning())
+  {
+    Serial.println(F("WARNING: RTC was not actively running, starting it now."));
+    rtcObject.SetIsRunning(true);
+  }
+  rtcObject.Enable32kHzPin(false);
+  rtcObject.SetSquareWavePin(DS3231SquareWavePin_ModeAlarmOne);
+  rtcObject.SetAlarmOne(alarm1);
+  rtcObject.LatchAlarmsTriggeredFlags();
+
+  // Uncomment this if you want to set the current time
+  //Wire.begin();
+  //RtcDateTime compileTime = RtcDateTime(__DATE__, __TIME__);
+  //rtcModule.SetDateTime(compileTime);
+
+  // Enable the interrupthandler to trigger when wakePin is signaled by the
+  // RTC-hardware; see the board layout image for details.
+  // Note that the interrupt mode is FALLING because the alarm interrupt in
+  // the DS3231 is active-low.
+  attachInterrupt(digitalPinToInterrupt(wakePin), handleInterrupt, FALLING);
+}
+
+//----------------------------------------------------------------------------
+// loop
+//----------------------------------------------------------------------------
+void loop() 
+{
+  // Check buttons
+  if (IncButton.pressed()) {
+    blinkDelay++;
+  }
+  if (DecButton.pressed()) {
+    blinkDelay--;
+  }
+
+  // Check if the RTC alarm has been triggered
+  if (alarmFlag == true) {
+    handleRtcAlarm();
+  }
+
+  // Update time values
+  updateTime();
+
+  // Update the display
+  oled.firstPage();
+  do {
+    updateDisplay();  
+  } while (oled.nextPage());
+
+  // Take a small break and relax
+  delay(20);
+}

README.md

@@ -89,7 +89,7 @@ To start doing this, we need to feed the things we have seen so far in the analy
 
 By starting RfCat, defining the function init(d) and calling it we have configured the CC1111-chip. To start listening we call d.RFlisten() and as you can see we start to get some packets.
 
-However, to be able to test the packet content better, we write a small Python script:
+However, to be able to test the packet content better, we write a small Python script. Take a moment to read it, in order to get an understanding of whats going on:
 
 ```python
 #=============================================================================
@@ -221,23 +221,31 @@ At this point, we know nothing of the internal packet layout, but we can start t
 
 ### Constants
 
- * Variable identifiers (data for variable X is always prepended with the constant Y)
+ * Variable identifiers (such as data for variable X is always prepended with the constant Y)
  * Length fields (packet length, length of individual fields in the packet, etc)
  * Sync words or other "magics" 
  * Sender identifiers (addresses, serials, hardware or software versions/revisions)
- * ...
+ * etc
 
 ### Variables
 
  * Timestamps
- * Things we see on the display
+ * Things we (in this case) see on the display
    * Current power usage seen on the display
    * Accumulative power consumption seen on the display
    * Battery life properties
  * Signal strength/RSSI if we're dealing with a two-way communication protocol
- * Extra crcs or other hashes
- * ...
+ * Extra crc's or other hashes
+ * etc
 
-The list goes on an on, but lets start with those elements for now. When identifying element-patterns we need to control the signal being sent as much as possible. Therefore we build this simple led-blinker with an Arduino board. The led is flashing at a predetermined rate which value we can observe on the receiving display. Other things we may consider to do is to hook up the sensor to a voltage cube and vary the input voltage. A third option is to decode signal for different senders which may have different sender properties or identifiers. 
+The list goes on an on, but lets start with those elements for now. When identifying element-patterns we need to control the signal being sent as much as possible. Therefore we build a simple led-blinker with an Arduino board. The led is flashing at a predetermined rate which we control. Knowing the stable flash rate we can observe what kWh they translate into on the receiving display. This is a good starting point for our analysis. Other things we may consider is to hook up the sensor to a voltage cube and vary the transmitters battery voltage. A third option is to purchase several Sparsnäs devices, and decode signals from the different senders which may have different sender properties or identifiers. 
+
+## Led blink helper tool
+<img src="LedBlinkerHelperTool/LedFlasher.png"  width="200" />
+<img src="LedBlinkerHelperTool/LedFlasher2.jpg"  width="246" />
+
+You can find the source code [here](LedBlinkerHelperTool/LedFlasher.ino).
+
+We hook up the Sparsnäs sensor to the red led to the right in the image above. Using the yellow and green push buttons we can increase or decrease the delay between led blinks, allowing us to experiment while running our RfCat on the side.
 
 XXX TODO: continue to document the analysis here