A Few Notes on my First Steps with panStamps

Introduction
What You Need
Programming
Sensor Power
Modem Connection
Gas Meter Reading
Electricity Meter Reading
Battery Boards
More panStamps
Additional Resources
Developing

and a few other bits...

Troubleshooting
NRG Problems
Building mspgcc
Building mspgcc on a Pi?
Building mspgcc on Another Pi
Raspberry Pi 2 and jessie
Raspberry Pi 2 and the official raspbian jessie

Introduction

This page is intended as a very quick run through on setting up panStamps as well as troubleshooting a few problems I had initially with NRG on both debian wheezy AMD64 and RaspberryPi and was originally written in February 2015.
Many things described herein may change so do check the official panStamp pages!
I have added strike-through tags (like this) to a few parts that are no longer applicable but I have left them in place for reference.

I recently bought a few panStamps, a panStick and a shield after reading about them on the fhem forum.

panStamps are small wireless modules that can be programmed using the Arduino IDE. They consume very little power and are ideal for monitoring of remote sensors etc.

They are ideal for situations where running wires is either impractical or impossible.

There is a lot of documentation in the wiki and on first reading I was totally lost.
Re-reading a few days later helped to make things much clearer.

The documentation is very detailed and both example code and sketches are provided. Do read it - and perhaps go back and re-read it!
You may notice that many of the sketch examples provided are quite short.
The general idea for these low power devices is that they spend as much time as possible sleeping, thereby using minimal power.

In simple terms when a connected sensor has something to send it triggers an interrupt, waking the panStamp which then takes in, processes, and transmits that data - and goes back to sleep.

What You Need

You will need panStamps of course. Plan for one to use as a modem as well as one for each remote location - and maybe some spares to play with :)

Make sure that one of your boards includes a sensor (see the NRG accessories), it will make your life much easier starting out.
You will also need something to program the boards as well as something to connect the modem panStamps to your computer - eg. a panStick.

The panStick is connected via USB and can be used for both programming the boards and connecting the modem panStamps to your computer to receive data from the others.

For the RaspberryPi the RPi shield is an alternative to a panStick, designed to be mounted on the GPIO pins of a Raspberry Pi (all models) and connects a modem panStamp through the GPIO pins.
It also has an RTC (Real Time Clock).

Once you have decided what you need you will need to order from the panStamp webstore.
If you have any queries or problems with your order use the Contact form (you will find it hard to beat their exceptionally helpful service).

My order arrived here in the UK within a few days.

v2 panStamps require a different panStick and the panStamps themselves are now small PCBs that can be soldered to a panStick or carrier board or used as they are. See the wiki for more details.
Soldering is a little more difficult but straightforward.

Programming

The recommended version of the Arduino IDE is 1.6.5 and higher.
The panStamp board and library have to be installed from their respective sections in the IDE. There is no more need for the patching mentioned above.

The python and lagarto downloads do still require a manual install - but with the help of a script there is little to it.

Programming v2 panStamps requires a different method to v1 devices as they are no longer plug-in devices.

Starting out, a panStamp should be mounted on a carrier board. In this way it can be programmed by placing the carrier board on the pins of a panStick (without a panStamp soldered to it) and using light pressure to ensure good contact between the two.
Programming a bare panStamp is a bit more difficult and requires a bit of ingenuity - follow the wiring instructions on the wiki.

The rest of the procedure is very much as described on the Arduino site here.

Load the modem sketch, select serial/USB port then board type as either panStamps NRG or panStamps AVR (v2) as well as msp430-gdb programmer for NRG or default for AVR.
If all has gone well you should now have a panStamp programmed as a modem. (If you have problems with the NRG programmer on your system see here).
Now do the same for the board with the sensor using the appropriate sketch and settings. (I used htusensor with a SI7021 sensor).

If you have purpose made antennae, attach these or use wire whips of the appropriate length (the length is important).
Attach the wire whip to the centre antenna pad. It's usually enough to pass the bared end through the hole and twist back on itself so that it doesn't fall out, no need to solder for testing purposes.
NB. If you use uninsulated wire be very, very careful that it doesn't touch and short anything nearby!

Tip: Keep track of the panStamps you have programmed, it's very difficult to tell from the outside what is on the inside ;)
Using different coloured wire for each whip may help with identification.

Sensor Power

The sensor board needs to be powered. Use two AA cells, a breadboard or patch leads and connect to VCC (+) and GND (-) (see the wiki pinouts for your board).
NB. Remember to keep to an absolute maximum of about 3.3V to be safe with these boards!

Modem Connection

Ideally your v2 panStamp modem will be attached to a panStick so plug this in to your computer

To use with fhem define it with something like
define mypanStick panStamp /dev/ttyUSB1
and it should connect.
From that same fhem web page
set mypanStick discover
should find your remote sensor.
See the fhem commandref for further configuration.
NB. fhem may grab any new sensor in which case it won't be available to lagarto on another machine. (note that fhem and lagarto cannot be run on the same machine!).
You can set the ignore attribute of the sensor in fhem so that it does communicate with lagarto.

Initially (back in February 2015) I had great difficulty getting lagarto show my device, suspecting both my abilities and the mixed system I am running now on the RPi 2.
I could see modem commands and responses in the console window but not in the lagarto pages.

So... I got out my B+, cloned my backup SD card. Same result :(

Finally I re-read the lagarto wiki page. Previously I must have overlooked the last bit and used the
python lagarto/lagarto.py
command.
If I run
python lagarto/lagarto-swap/lagarto-swap.py
my device appears in the web page at http://127.0.0.1:8001!

Doesn't reflect very well on my abilities at all :(

You can also try
python swapdmt/pyswapdmtgui.py
hopefully you will see your device and the sensor data. Personally I found this application easier to use and see results at the start.

Whichever application you use you should see traffic in the terminal window from which you started either lagarto or swapdmtgui.

Now you can see your device it's a good idea to change its address and TX interval, the first to avoid adding a new device with the same default address, the second to see data when you want it.
You can do this from both lagarto and swapdmtgui as well the CLI swapdmt.
You will probably see a message about putting your device in sync mode or that it will save the command for next sync.

Most of the sketches have a few lines of code in the setup function that toggle the LEDs to indicate that the panStamp is listening for commands. This mode usually only lasts for a few seconds. lagarto will send new address and interval settings at this point.

swapdmtgui should do the same if you can see the sync notification window on screen.

You can force the panStamp into sync mode either by unplugging and re-inserting the panStick to its USB socket or by pressing the reset button on the panStick.

Removing power from a standalone panStamp should achieve the same result but it may need remain without power for some seconds or it may not reset.

I have had much better luck with recent versions running on a jessie Pi - and in current versions of lagarto, ZeroMQ has now been replaced with MQTT.

Gas Meter Reading

In this section I hope to describe using a panStamp to record data from my gas meter which is located outside on a flank wall. A panStamp seems an ideal solution.

I have tried this on a breadboard and it was surprisingly easy.

The pulsecounter sketch works for both AVR and NRG boards and will record pulses using interrupts, and add each occurrence of an interrupt to a counter.

At intervals the contents of the counter are transmitted for the modem panStamp to receive.

I shall be using a purpose-made pulse block but a reed switch should work just as well.
Reading meters is often linked with S0 reading although I believe S0 has more to do with devices that have a built-in electronic interface of some kind.

Let's take a closer look.

My meter is a BK-G4 and has a small magnet incorporated in the rightmost index wheel, the wheel that records thousandths of a m³, so every revolution of this wheel and resulting pulse from the sensor should equate to one hundredth of a m³ consumed.
The passing of the magnet can be sensed using any device that will react to it, a typical example would be a reed switch.

You can easily check whether your own meter has a magnetic wheel, simply hold a magnetic (orienteering) compass close to it. If the needle displacement varies as the wheel turns then it has a magnet :)
I managed to locate a purpose made device that fits onto my meter, it is known as a pulse block and this specific one is an IN-Z61.They are available online but perhaps not very easy to find.

I had expected the connection to be a 3.5mm jack socket. In fact it's an RJ11 modular socket (4 wire telephone type) and there is an additional alarm/anti-tamper switch incorporated.
The centre pair of wires in the plug are attached to the sensor switch, the outer pair to the alarm switch.

If we look at the code in the pulsecounter sketch we will see that it is designed to generate an interrupt as the voltage is RISING on a specific pin.
Elsewhere in the sketch the relevant pin number is given as 18 or 22 depending on whether you are using an AVR or NRG panStamp - 18 for AVR v1, 22 for NRG v1.

We connect one side of our reed switch or pulse block to ground, the other to the interrupt pin. As the switch is closed it pulls the pin LOW (to ground potential) then as it opens shortly after the pin is pulled back up to a HIGH state.
As its voltage rises to HIGH the interrupt will be triggered and a unit added to the counter.

Except it probably won't do that as it is set up so far!
The voltage on the interrupt pin is likely to be floating at a level that is neither HIGH nor LOW, as there is no means of pulling it one way or another.
An internal or external pullup resistor needs to be added keep the pin HIGH until grounded by the switch closing.

To make things more obvious visually add a 100kΩ resistor between the interrupt pin and VCC to pull the pin HIGH.

That's it. All done :)

If we connect the panStamp to a couple of AA cells we should be able to start measuring gas consumption and should see the counter incrementing.

I now have a new RPi 2 so here are some rather rushed Fritzing images - these and the ones for the electricity meter monitoring are of the breadboard prototypes but have now been tested and are both working..

panStamp breadboard gas meter monitor images created in Fritzing
Breadboard note the pullup resistor.	Schematic.

Electricity Meter Reading

My electricity meter is a fairly typical for a UK model that has a flashing LED. The rate at which it flashes depends on usage and mine indicates that it flashes one thousand times for each kWh used.
We should be able to use a similar method to read this as for the gas meter.

I have a TAOS TSL260 in my bits box that may make a suitable sensor. The TSL260 generates a voltage when illuminated by IR light - using an IR sensitive device may help to reduce interference from other light sources - I hope. (The package is black, not clear, as it might be for visible light.)
The device has three 'legs' (see the datasheet). GND and V_DD for power, connect to GND and VCC respectively, OUT is the sensor output that we will connect to the interrupt pin.

We can check to see if this works as we hope by connecting it to a battery and then, with a multimeter between GND and OUT, see whether a voltage registers when the LED flashes.
A pulse of the LED will generate a voltage on the output and pull the interrupt pin HIGH rather than LOW as was the case with the switch on the gas meter.

We could use additional components to reverse this action so that it behaves exactly as the switch did - or better we can use a 100kΩ pulldown resistor between the interrupt pin and ground to pull the pin LOW so that a pulse from the TSL260 will pull the pin HIGH and trigger the interrupt. We can also change the interrupt statement in the sketch so that an interrupt is generated on FALLING ie. as the LED flash finishes. (In tests using a RISING or FALLING interrupt seems to make no significant difference.)

All done again :)

Connect power to the panStamp and attach the TSL260 to the meter temporarily with some 'tac' and we should see the counter incrementing.

panStamp breadboard gas meter monitor images created in Fritzing
Breadboard note the pulldown resistor.	Schematic.

Battery Boards

The two sections above are only proof of concept but they do both work on the breadboards.
I have ordered some panStamp battery boards that I intend to use to install these two panStamps permanently. I hope to be able to write about a successful installation quite soon.

The battery boards arrived - I finalised my order on Wednesday morning and it was delivered here on Saturday morning!
Just like my first order, I received an almost empty box - that's not a complaint - and there is a lot of protective packaging inside. I was simply surprised yet again how small these devices are.

The battery boards themselves are about 50 x 70mm (v1.1) and that includes the area for the single AA cell.
I have now assembled a couple more panStamps along with two battery boards and fixed them temporarily, as bare boards, to my gas and electric meters and... I have working counters!
Note that these are both using the supplied pulsecounter sketch.

I set TX intervals to 60 seconds so that I could see results sooner than with the default setting.

Gas counting looked good from the start but the electricity counter appeared to be adding about three pulses at a time.
Reducing the TX interval to 10 seconds shows it is actually counting correctly. I guess a single Watt hour doesn't take long to consume (1000 pulses per kWh).

My next step is to find a weatherproof box for the gas meter counter (the battery board enclosures have vent holes top and bottom so not ideal for external installation) and some means of securing the TSL260 sensor against the electricity meter window directly above the flashing LED as well as excluding external light interference.
The latter is going to be the most difficult I think.

The two sensors have now been installed and seem to be working as expected although I have not yet integrated them into fhem.
The gas counter is now mounted in an IP65 box to the side of the meter box (not inside the meter box, they don't like that!), the electricity in a panStamp battery board housing. I have not yet found a suitable method of holding the TSL260, it is still attached with tac!

panStamp gas meter batteryboard monitor images created in Fritzing
the pullup resistor illustrated is in construction a 0603 size SMD added to an unpopulated location on the battery board underneath the panStamp.	the panStamp pins (panStamp is superimposed on the battery board schematic) connect to pins on the battery board schematic hence the ratsnest in the middle

As noted in the caption above, the battery board has a number of unpopulated positions for pullup resistors for the various connection points if required.
Adding them is not quite as easy as it sounds, the pads are set out for 0603 footprint components and an 0603 is 0.06" x 0.03" or 1.6mm x 0.8mm.
If you think that's easy, try and draw one with pencil and paper ;)

panStamp electricity meter batteryboard monitor images created in Fritzing
the VCC feed illustrated is in actual construction taken from a point on the battery board underneath the panStamp. As the TLS260 takes the signal lead high on a pulse a pulldown resistor has been added to the underside of the battery board, not as shown in in the image.	see note above regarding the ratsnest at the centre.

panStamp pulsecounter plot from fhem
	Plot of the counts transmitted by the two pulsecounters.

The pulsecounter sketch increments the counter on each interrupt and the current counter value is transmitted at the chosen interval.
This means that should a transmission fail for any reason the counter value is maintained and added to for the next transmission.
If the counter were reset on transmission there is a danger of losing data - the panStamp has no way of knowing whether its transmission was actually received.

Another pulsecounter plot
	Sometimes it seems as though the gas counter has gone to sleep permanently!

As you can see from the above image no data was received from the gas counter for some hours.

There may, of course, be the odd missed transmission but the sketch has been written so that the panStamp only transmits if there has been a change in the counter value. My boiler has a pilot light so there is always some consumption but this may not be enough to use one hundredth of a cubic meter between transmissions.

My fhem definition for the electricity meter pulsecounter is...

Note the use of the modifier difference.
Any new reading triggers a notify...

Note the use of the ternary operator to discard any negative values that may result from a reset of the panStamp.

Update after many months of running..
The gas counter is 100% accurate. I still check my meter every week and it has not faltered.
The electricity counter is less accurate and always reads a bit more than I have consumed but not by a predictable amount.
I suspect stray light passing through the main viewing window is affecting the count.

More panStamps

I really like these devices, in case you hadn't noticed. They are just so easy to use with the supplied sketches as well as providing scope for more complex applications.
I think another order is imminent!

I have long had a plan to install temperature and humidity sensors in each room and my intention has always been to use 1-wire. Needless to say, it hasn't happened, there is always something more interesting to do than moving furniture, taking up carpets and pulling up floorboards.
It occurred to me this morning that it would be so much easier, and cheaper too, to use panStamps instead of 1-wire.
I already have enough 80mm square sensor enclosures that will take two AAA or AA cells and a panStamp (NRG with SI7021 chip).

My latest order has arrived and here is an image of one of the sensors made up..

panStamp temperature and humidity sensor
	panStamp NRG and two AA cells installed in an 80mm square sensor housing.

They are each labelled as you can see with the panStamp device address so that I can tell them apart.
Note that I have not soldered any pins to these panStamps, they were each programmed using GPIO patch leads and a panStick (done on an RPi2).

The panStamp itself is held in place using a short length of 16mm plastic electrical trunking and allows air circulation to both sides of the board. The trunking and battery housing are both hot-melt glued to the sensor housing. (The hot-melt glue failed after a while, now upgraded to silicone mastic.)

panStamp temperature and humidity sensor plot from fhem<</th>
	Dewpoint and absolute humidity are calculated automatically by fhem.

A later image of all my temperature and humidity sensors.
	All sensors in a readingsGroup.

The timestamp is a temporary addition whilst I find the best location for one of the sensors.

Later...
It seems that the odd late or delayed updates from a couple of sensors were due to my wire whip antenna on the panStick/panStamp modem.
I have had an 868MHz stub antenna and SMA adapter sitting in a drawer for many months and I finally got around to soldering it to the modem.
Reception has improved dramatically!

Next project is to transfer my heating flow and return sensors from 1-wire to a panStamp.
They are in an awkward location with cable running under carpet at present as it is difficult to route within the floor void.
After some searching I came across an existing sketch temphumpress_onewire by IulianV that works with the current API after a few minor tweaks.

Additional Resources

As I mentioned earlier, there is a wealth of information in the panStamp wiki pages but a few other sources may be useful.
There are some concepts and methods that may be new and a little difficult to understand when first encountered.

For many who have played with Arduinos before perhaps one of these is confusion regarding pin numbers or names.
The Arduino site is a very good place to start, see Port Manipulation and the very comprehensive BitMath tutorial. There are, no doubt, many good tips to be found within the forum too.

I have created my own table of panStamp pinouts to save me having to look them up each time. It may be useful to others.

For those like me who still find books with real paper pages useful, I recommend The Arduino Cookbook as a very good general guide to Arduinos. The link is to a sampler so you can see a bit before you buy.

Neopixels and a bit of Developing

A lot has changed since I wrote most of this page and there is a now a new generation of panStamps.
Same principle but different packaging and to make life easier new boards to mount them on.

Arduino IDE 1.6.6 has been released but it's not working here at present with panStamps so I'm still using 1.6.5.

The example sketches now include a basic sketch for using WS2812 Neopixels with NRGs. The sketch works and lights up pixels but not in a useful and fully controllable way at present.
A great shame as I would have liked to use this as a basis to resurrect my status display project which ground to a halt much earlier in the year, mainly because it requires both power and serial connections.

I wondered if an AVR panStamp could be used as it is based on an Atmega 328 - but of course it runs at 8MHz whereas Arduino Uno and 5V Pro Mini are both 16MHz.
After a little searching I found that the light_WS2812 library that I used in my previous Arduino attempt has been rewritten and now supports multiple frequency micro-controllers - looks worth a try :).
Note: before setting things up, Neopixels need a 5V supply, panStamp 3V and best advice is to use a level shifter for the data output. 5V on a panStamp pin will kill it!

Adding modified bits of my previous code into the panStamp binouts2 sketch seemed to be OK but of course panStamp sketches use completely different input and output methods tied closely to SWAP.
Back to reading the wiki docs again. Several times again in fact (I wish they were available as PDFs for offline reference). I looked long and hard at the panStamp example sketches along with the very few others I could find online.

Much of the code and methods are beyond my comfort level so it took a long, long time to take in - but I got there in the end.

I'm sure many will find developing for panStamps relatively easy and be able to jump in straight away but for those like myself who are struggling this is a quick run-through of my experiences - some of my assumptions may be incorrect of course - my working life was spent building houses not code :).

The first thing that struck me was that I had almost completely overlooked the importance of the <device>.xml files but in fact they are an essential part of the whole in that they define how a register is split into various fields to be used from the SWAP registers in your sketch.

Once I had grasped this things became much easier

As an example my sketch requires a byte for a command (cmd), another for led index then three separate bytes for red, green and blue values.
The SWAP register in the sketch I have defined as 5 bytes and <device>.xml has to represent these exactly. Mine is...

The first register PWM output 0 is my output pin, the third, LEDs is where I place the number of LEDs defined in the sketch (transferred back to the application, in my case fhem but it could be lagarto or swapdmt or some other app).
In fhem the number of LEDs appears in Readings.

Note: Registers are numbered from 11 up (id="11").

Add the <device>.xml to the location of others on your machine using a suitable name. I didn't have a developer ID initially so used the panStamp one.
I named mine test.xml and and added it to /opt/fhem/FHEM/lib/SWAP/panStamp/.
Reference to test.xml now has to be added to devices.xml (one level up).
I placed this under the panStamp ID and gave it the dev ID of 999. This requires a change to SWAP_PRODUCT_ID in product.h so I replaced the last three characters with 3E7 (hex 999).

Note that these two xml files may be overwritten at times from central repositories so keep copies!

fhem also uses devices-local.xml which I believe gets around this but I haven't investigated/translated further so far - something for another day.

Later...
I have now looked at and tried this.
I believe from an initial test that you can place your own devices in devices-local.xml.
However, devices under the same developer id will not be read from the main <device>.xml.

Example setters and updaters are given in the wiki docs and are relatively easily adapted, SWAP does much of the work for you once these are in place.
Note: Read the references to endian-ness (BE, LE) in the wiki and the need to compensate for this with byte swapping.
You now add your code and and reference the now defined inputs and outputs.

In my case input is the command, sent by wireless message from fhem, output is the above defined pin which supplies data to the Neopixel stick (via a level-shifter and recommended resistor in the data line).
I have no need for power-saving/sleep in this sketch.

That is sort of all there is to it - but anyone following this may still need to do a lot of reading - and head scratching too :)

I am running panStamps in fhem and fhem grabs any new device (not a problem, just precludes the use of panStamp tools by default but, as I mentioned earlier, setting the ignore attribute will allow this) and although I was able to see bits of data it wasn't until I had correctly set up <device>.xml and devices.xml that the data became useful and meaningful.
I suspect that development using the panStamp tools lagarto or swapdmt would also require xml files to be set correctly.

So now, how do I send commands to the panStamp from fhem?

There are two SWAP modules for specific devices as well as a generic SWAP module available within fhem.
I took a long, hard look at these, again the code is outside my comfort level, but going through slowly I began to understand it (some of it anyway).
I was able to put a module together, specifically for my application that sends commands in the required format.

I'm quite pleased with myself :)

Just need a new panStamp (more on the way now) and to tidy up my various bits of code to finish it all off.

I'll try and summarise even more briefly...

• Choose and copy one of the panStamp example sketches that does the sort of thing that you want to achieve.
• Comment out any pins or registers and their associated entries that you don't need - (don't delete them, you may need to refer back). Remember the locations of these entries!
• Add any new registers and their associated entries in the locations you remembered above. Size of registers will depend on your input/output data.
• Add and set up setters and updaters for your registers as well as their associated set and update functions.
• Create and add your <device>.xml Add its reference to devices.xml.
• If you are using a sensor with a sketch based on one of the sensor examples and have added/modified things correctly you should now be able to upload to your panStamp and see some data from the sensor when swap.getRegister(your_code) runs.
• If you have a sketch based on one of the examples that expects data via SWAP you will have to send it some data!
• If all is OK at this stage you can now add any additional code to your sketch.

Please let me know if I have missed anything - or misled anyone - or broken anything tidying up this page. Have fun.

Reference Section

Troubleshooting

NRG Problems

Building mspgcc

Building mspgcc on a Pi?

Building mspgcc on Another Pi

Raspberry Pi 2 and jessie

Raspberry Pi 2 and the official raspbian jessie