Libelium Waspmote User manual

Waspmote Plug & Sense!
Quickstart Guide

-2-
v4.5
Index
Document version: v4.5 - 11/2014
© Libelium Comunicaciones Distribuidas S.L.
INDEX
1. Introduction......................................................................................................................................... 3
2. General and safety information ......................................................................................................... 4
3. Waspmote Plug & Sense!’s Hardware Setup ...................................................................................... 5
3.1. ON/OFF Button ............................................................................................................................................................................5
3.2. External LED...................................................................................................................................................................................6
3.3. Resetting Waspmote Plug & Sense! with an external magnet ....................................................................................6
3.4. USB ....................................................................................................................................................................................................8
3.4.1. External SIM socket....................................................................................................................................................10
3.5. Antenna........................................................................................................................................................................................12
4. Waspmote IDE: Download and Installation..................................................................................... 14
4.1. Linux ..............................................................................................................................................................................................14
4.2. Windows.......................................................................................................................................................................................14
4.3. Mac.................................................................................................................................................................................................15
5. Receiving Frames from Waspmote Plug & Sense! ........................................................................... 16
5.1. In the Waspmote Gateway.....................................................................................................................................................16
5.2. In Meshlium ................................................................................................................................................................................17
6. Compiling a New Program ................................................................................................................ 18
7. Uploading a New Program to Waspmote Plug & Sense!................................................................. 20
8. Next Steps: using the Developers Guides....................................................................................... 26
9. Documentation Changelog .............................................................................................................. 27

-3-
v4.5
Waspmote Plug & Sense! - Quickstart Guide
1. Introduction
The aim of this Guide is to introduce the user to Waspmote Plug & Sense! in a practical way.
Waspmote Plug & Sense! is a complex device and a learning process must be completed. Libelium oers many Guides and
examples which will help the developer.
The present Guide was created in the hope of helping the developer in the very rst steps with Waspmote Plug & Sense!. We
advice to follow this Guide when the user wants to start the learning process. The last chapter will try to plan a learning process,
proposing further steps.

-4-
v4.5
Waspmote Plug & Sense! - Quickstart Guide
2. General and safety information
Software:
• Upload code only using Waspmote IDE. If a dierent IDE is used, Waspmote can be damaged and can become
unresponsive. This use is not covered under warranty.
• Do not unplug any connector while uploading code. Waspmote can become unresponsive. This use is not covered under
warranty.
• Do not connect or disconnect any connector while Waspmote is ON. Waspmote can become unstable or unresponsive,
and internal parts can be damaged. This fact is not covered under warranty.
Hardware:
• Do not handle black stickers seals on both sides of the enclosure (Warranty stickers). Their integrity is the proof that
Waspmote Plug & Sense! has not been opened. If they have been handled, damaged or broken, the warranty is void.
• Do not open Waspmote Plug & Sense! in any case. This will automatically make the warranty void.
• Do not handle the four metallic screws of Waspmote Plug & Sense!. They ensures waterproof seal.
• Do not submerge Waspmote Plug & Sense! in liquids.
• Do not place nodes on places or equipment where it could be exposed to shocks and/or big vibrations.
• Do not expose Waspmote Plug & Sense! to temperatures below -10ºC or above 50ºC.
• Do not powerWaspmote with other power sources than the original provided by Libelium.Voltage and current maximum
ratings can be exceeded, stopping Waspmote working and voiding warranty.
• Do not try to extract, screw, break or move Waspmote Plug & Sense! connectors far from necessary usage, waterproof
sealing can be damaged and warranty will be voided. For more information: http://www.libelium.com
• Do not connect any sensor on the solar panel connector and also do not connect the solar panel to any of sensor
connectors. Waspmote can be damaged and warranty void.
• Do not connect any sensor not provided by Libelium.
• Do not place Waspmote Plug & Sense! where water can reach internal parts of sensors.

-5-
v4.5
Waspmote Plug & Sense! - Quickstart Guide
3. Waspmote Plug & Sense!’s Hardware Setup
For the advanced hardware setup, please consult the Waspmote Plug & Sense! Technical Guide. Here we show the most basic
points about the hardware conguration:
3.1. ON/OFF Button
This button is used to turn ON or OFF Waspmote. It is a latch type button with two static positions as shown below. In ON
position, the button remains a bit lower than LED ring.
Figure : On / O button at o position
Figure : Turning On Waspmote

-6-
v4.5
Waspmote Plug & Sense! - Quickstart Guide
3.2. External LED
ON / OFF button includes a red ring led, which can be managed by software. This led can be used for instance to know that
Waspmote is ON, or for debugging purposes at developing phase. By default, Waspmote Plug & Sense! comes with a code that
blinks briey (3 times in less than one second) this led when it is turned ON. The LED can be managed specifying ON time or
just setting this state with specic API functions. The user should take into account that the usage of this led will increase power
consumption due to external LED consumes 4.4 mA.
Figure : Waspmote turned On
3.3. Resetting Waspmote Plug & Sense! with an external magnet
Waspmote Plug & Sense! it can be reset with an external magnet, with no contact. If one node stops working or if a defective
behavior is detected, it would be costly to uninstall the node to bring it back to laboratory. This feature allows the network
manager to reset the node in a quick and easy way.
The hardware consists of a reed switch connected to the Waspmote reset line. When the user gets the magnet close to the reed-
switch, the reset is activated. When the user moves the magnet away, the reset line is released (the external LED will blink) and
Waspmote executes the bootloader rst and then, the setup function. After the setup, it will continue with the loop function.
Next pictures shows the right way to reset the node using an external magnet, rst moving it closer, and then moving it away.
Figure : Moving the magnet closer to the node.

-7-
v4.5
Waspmote Plug & Sense! - Quickstart Guide
Figure : Moving the magnet away from the node.
The magnet is made of neodymium. It is a special, high-power magnet. We only advise to use the magnet Libelium provides.
It is not mandatory, but highly recommended to consider this feature when designing the project. The user should design the
software in a way the node can be reset if things go wrong. Remember that laboratory tests are always needed to validate the
feature before your nal deployment.
When the node is already deployed in the eld, and for instance it is installed in a trac light, this feature can be used to reset
the node easily, as it is shown in the diagram below, where a technician uses a pole with the magnet attached in one side.
Figure : Applying the magnet in a real deployment

-8-
v4.5
Waspmote Plug & Sense! - Quickstart Guide
3.4. USB
This connector is used to upload code into Waspmote with a male to male USB cable provided by Libelium. Just connect one
side of the cable to this connector, removing protection cap and connect the other side to a PC to upload a code or to charge
the battery in case your model has a rechargeable battery. Next picture shows an example.
Figure : USB connector and protective cap
Figure : Connecting the USB cable to Waspmote
When uploading processes are nished, do not forget to screw rmly the protection cap to avoid connector damage. Never
connect a USB which exceed maximum ratings of USB standard.

-9-
v4.5
Waspmote Plug & Sense! - Quickstart Guide
Figure : Connecting USB charger
For indoor deployments the nodes can be recharged using the USB charger.
Important: Use the USB charger just with the models which includes rechargeable battery.
Figure : Charging the mote by USB

-10-
v4.5
Waspmote Plug & Sense! - Quickstart Guide
3.4.1. External SIM socket
The External SIM socket replaces the USB socket in two devices:
• Waspmote Plug & Sense! devices with GPRS module, GPRS+GPS or 3G module
• Meshlium devices with 3G/GPRS module
The External SIM socket is composed of 2 connectors:
• micro-SIM card
• micro-USB (type B)
Figure : External SIM socket in a Plug & Sense! with GPRS, GPRS+GPS or 3G module
The operation with the micro-USB socket is just the same than with the normal USB socket. Just remember to use a micro-USB
cable.
Figure : Connecting the micro-USB cable to Plug & Sense!

-11-
v4.5
Waspmote Plug & Sense! - Quickstart Guide
The micro-SIM card connector allows now the user to connect the SIM card he likes from the outside. It is no longer necessary
to send a SIM card to Libelium for proper installation. You can ask your telecommunication provider for a micro-SIM card.
Alternatively you can take a normal SIM card and transform it into a micro-SIM card with a SIM card cutter.
Besides, the micro-SIM card connector has a push-pull mechanism, so it is really easy to remove the card with the aid of one nail.
Figure : Push-pull mechanism in the External SIM socket
It is highly important to turn o the Plug & Sense! device in a secure way before inserting a micro-SIM card, or removing an
existing SIM-card. The user can damage the device if this operation is done“on-the-y”.
Make sure you closed the External SIM socket with its protection cap before outdoors deployment.
Take into account that the External SIM socket has a limited resistance so please be gentle and do not push too hard with the
USB or SIM card.
Figure : Inserting a SIM card with care in the External SIM socket

-12-
v4.5
Waspmote Plug & Sense! - Quickstart Guide
3.5. Antenna
By default Waspmote Plug & Sense! has one external antenna of 5dBm with a standard reverse polarized SMA connector. This
connector allows to connect the RF antenna.
Figure : Antenna connector of the enclosure
To ensure good RF coverage, be sure antenna points to the sky and also be sure antenna is screwed completely to the connector.
To connect the antenna, just align it with the connector and screw it carefully. Antenna must be connected in order to ensure
RF communication.
Figure : Connecting antenna to the enclosure
Note: Once Waspmote Plug & Sense! is installed, it is recommended to x it using a tape like the one shown in the picture below.

-13-
v4.5
Waspmote Plug & Sense! - Quickstart Guide
Figure : Recommended tape Figure : Ensure antenna remains in the right position
Do not try to connect other kind of antennas which do not match with SMA RP standard connector and also other antennas not
provided by Libelium.

-14-
v4.5
Waspmote Plug & Sense! - Quickstart Guide
4. Waspmote IDE: Download and Installation
The rst step is to install the Waspmote IDE (Integrated Development Environment).
This IDE can be found on:
http://www.libelium.com/development/plug_&_sense/sdk_and_applications
The Waspmote IDE is based on the open source Arduino platform compiler, following the same style of libraries and operation.
It is important to use the version found on Libelium website and no other version of Arduino IDE. This is because the version
available on the Libelium website has been properly tested and for which we can assure optimum operation.
To be able to run the compilation from a code successfully a series of applications must be installed on the computer. The
applications to install vary according to the O.S. used.
4.1. Linux
Waspmote Plug & Sense! can be programmed using any of the many available Linux distributions. Libelium ensures stability of
the Waspmote IDE using the Debian and Ubuntu distributions, as they have been used during development. The process for
Ubuntu 9.04 is explained below.
To be able to correctly compile and use Waspmote it is necessary to install some packets related with the version of the compiler
for Atmel microcontrollers and Java environment.
1. Installing Java
The next step is to install the necessary version of the avr-gcc compiler to be able to program the Waspmote Plug & Sense!
microcontroller. We can use the Synaptic package manager or a terminal. Using Synaptic we must look for the“gcc-avr”package
and install it. Using the terminal we must use the apt-get command in the following way:
$ sudo apt-get install sun-java6-jre
2. Installing AVR-GCC Compiler
The next step is to install the necessary version of the avr-gcc compiler to be able to program the Waspmote Plug & Sense!
microcontroller. We can use the Synaptic package manager or a terminal.
Using Synaptic we must look for the “gcc-avr” package and install it. Using the terminal we must use the apt-get command in
the following way:
$ sudo apt-get install gcc-avr
3. Installing lib-avc Library
The next step is to install the necessary version of the lib-avc library. We can use the Synaptic package manager or a terminal.
Using Synaptic we must look for the “lib-avc” package and install it. Using the terminal we must use the apt-get command in
the following way:
$ sudo apt-get install avr-libc
4.- Installing Waspmote IDE
Waspmote IDE installation entails unzipping the le downloaded in the previous step to the chosen folder. Once the downloaded
le has been unzipped, the le called Waspmote must be run to launch the IDE.

-15-
v4.5
Waspmote Plug & Sense! - Quickstart Guide
4.2. Windows
The process for installing Waspmote IDE on a computer with Window XP SP3 is explained below.
1. Downloading Waspmote IDE
The rst step is to download the le that contains the environment and the libraries (the IDE).
This le can be found at :
http://www.libelium.com/development/plug_&_sense/sdk_and_applications
2. Installing Waspmote IDE
The next step is to unzip the downloaded le to the chosen folder. This folder includes the drivers needed in the next step to
install the USB and FTDI converter.
3. Connecting Waspmote Plug & Sense!
When connecting a Waspmote Plug & Sense! using the USB connector, the message“New device found” will appear. A window
will open for the installation of this device.
Select the option “Not right now” and press the‘Next’ button.
Next select the path where the drivers for the FTDI converter are. These drivers are in the folder where Waspmote was unzipped.
Then proceed to the installation of the FTDI converter drivers, which shows the following message when nished.
Once installation is nished, the message‘New device found’ will appear, referring to the USB. The same process carried out for
the FTDI converter must now be followed, choosing the same options in all the windows. The path for the drivers is the same as
that previously specied.
Once this installation is nished, a message will appear indicating the correct installation of the USB.
Once both devices are correctly installed, the port on which the Waspmote board has been installed will appear in the“Device
manager”.
4.3. Mac
Waspmote Plug & Sense! can be programmed using the Mac OS X operating system. The process of install Waspmote IDE on a
computer with a version later than 10.3.9 is explained below.
1. Downloading Waspmote IDE
The rst step is to download the le that contains the environment and libraries (the IDE).
This le can be found on our web page http://www.libelium.com/development/plug_&_sense/sdk_and_applications
2. Installing Waspmote IDE
The next step is to unzip the downloaded le to the chosen folder. The drivers needed in the next step to install the FTDI
converter are found in this folder.
3. Installing FTDI converter drivers
Waspmote requires the installation of the FTDI converter drivers. These drivers are found in the downloaded le.
Once the drivers are installed for the FTDI converter, the Waspmote board can be connected and the system will recognize it
correctly.

-16-
v4.5
Waspmote Plug & Sense! - Quickstart Guide
5. Receiving Frames from Waspmote Plug & Sense!
5.1. In the Waspmote Gateway
Waspmote Plug & Sense! comes precongured from factory with a program which lets you check the right operation of the
device. This program sends standard frames to the Gateway. It is called wasp_pro_test_code.pde and is always available inside
the IDE and on this link:
www.libelium.com/development/waspmote/examples/waspmote-pro-test-code
This program sends wireless frames for the following radio modules:
• XBee 802.15.4
• XBee 868MHz
• XBee 900MHz
• XBee Digimesh
• XBee ZigBee
• LoRa
For other modules, the program works, but connectivity is limited to send frames via USB.
Steps:
1. Install the drivers and the serial monitor software on the computer.
2. Connect the antennas and the rest of the desired components to Waspmote Plug & Sense! and Waspmote Gateway.
3. Connect Waspmote Gateway to the USB port on the computer.
4. Launch the IDE’s serial monitor application and set the USB port baudrate at 115200bps
5. Switch Waspmote Plug & Sense! to the ON position.
When the program starts, it executes sequentially these actions:
• State 1 – External LED ON for 0.5 seconds
• State 2 – External LED blinking for 0.5 seconds
• State 3 – Sending messages (blink External LED shortly with each frame)
State 1 and 2 are only executed once (when program starts) whereas state 3 will loop indenitely every second (if we reset
Waspmote, the program starts again).
Every packet contains a message with sensor data formatted asWaspmote Data Frame. The sensor elds added to the frame are:
Accelerometer values, RTC internal temperature value, and battery level. In the case the XBee is not using DigiMesh protocol,
then the MAC address is added (because of length constraints). For further information, please check the Waspmote Data Frame
Guide:
http://www.libelium.com/development/plug-sense/documentation/?cat=programming
Example:
~\0x00I\0x90\0x00}3\0xa2\0x00@z\0xcb\0x92\0xd8\0xd3\0x02<=>\0x80\0x03#35689722##7#ACC:80;10
;987#IN_TEMP:22.50#BAT:93#\0xb4
Initially there are some hexadecimal characters, which belong to the frame header, followed by the message. In the above
example the message is:
<=>\0x80\0x03#35689722##7#ACC:80;10;987#IN_TEMP:22.50#BAT:93#

-17-
v4.5
Waspmote Plug & Sense! - Quickstart Guide
5.2. In Meshlium
When you buy a kit containing Meshlium and Waspmote, your Waspmtes already come congured to send frames to the
Gateway. Later, once the user has developed the code for transmitting to Gateway, he can switch to Meshlium.
Before sending frames to Meshlium, we recommend you read and study the networking guide for your module:
• Waspmote 802.15.4 Networking Guide
• Waspmote 868MHz Networking Guide
• Waspmote 900MHz Networking Guide
• Waspmote Digimesh Networking Guide
• Waspmote ZigBee Networking Guide
• Waspmote LoRa Networking Guide
• Waspmote WiFi Networking Guide
• Waspmote 3G+GPS Networking Guide
• Waspmote GPRS Pro Networking Guide
• Waspmote GPRS+GPS Networking Guide
Meshlium will receive the sensor data sent by Waspmote using the radio module and it will store the frames in the Local
Database. That can be done in an automatic way thanks to the Sensor Parser.
The Sensor Parser is a feature for Meshlium (version 3.0.5 or older). It is a software system which is able to do the following tasks
in an easy and transparent way:
• receive frames from XBee / LoRa / WiFi / 3G / GPRS (with the Data Frame format)
• parse these frames
• store the data in local Database
• synchronize the local Database with an external Database
Besides, the user can add his own sensors.

-18-
v4.5
Waspmote Plug & Sense! - Quickstart Guide
6. Compiling a New Program
To use the Waspmote IDE compiler we must run the executable script called ‘Waspmote’, which is in the folder where the
compiler has been installed.
Waspmote IDE is divided into 4 main parts which can be seen in the following gure.
IDE options
Buttons: opening and
uploading codes
Main Code
Output messages
Figure : IDE – Waspmote parts
• The rst part is the menu which allows conguration of general parameters such as the selected serial port.
• The second part is a button menu which allows compilation, opening, saving or loading the selected code on the board.
• The third part contains the main code which will load in Waspmote and the fourth part shows us the possible compilation
and load errors, as well as the success messages if the process is carried out correctly.
The Waspmote IDE buttons panel allows certain functions to be carried out such as opening a previously saved code, creating a
new one or loading the code on the board. The following gure shows the panel and the functions of each button.
Figure : IDE – Waspmote panel of buttons

-19-
v4.5
Waspmote Plug & Sense! - Quickstart Guide
The next step is to congure the folder where the created programs are going to be saved. In the Waspmote IDE, this folder is
called ‘sketchbook’ and can be congured by accessing the ‘File/Preferences’ tab. Clicking on this tab will open a new window
where the location of the sketchbook can be indicated. Once the sketchbook folder path is indicated, the downloaded test
program must be saved in this folder.
Waspmote IDE must be closed so that the changes and the newly saved program in the sketchbook folder are reected.
Note: The Gateway is just a UART-USB bridge. This means that the Gateway cannot be programmed and code cannot be uploaded. Its
function is to pass data from the XBee or LoRa module to the USB, and vice-versa.

-20-
v4.5
Waspmote Plug & Sense! - Quickstart Guide
7. Uploading a New Program to Waspmote Plug & Sense!
Using the USB connector, a new code can be uploaded to Waspmote without opening Waspmote Plug & Sense!. Just connect
one side of the USB cable to this connector, removing protection cap if necessary and connect the other side to a PC. Remember
that Waspmote must be ON to allow uploading a new code. Next steps describe this process in detail.
Step 1: Open the USB connector
Remove the protection cap of the USB connector.
Figure : Removing the USB cap
* In the case you have a Plug & Sense! With GPRS, GPRS+GPS or 3G module, insert your micro-SIM card in the External SIM socket with care.
Figure : Inserting a SIM card with care in the External SIM socket