Waspmote InterruptionsProgramming Guide

-2- v4.1

Index

INDEX

1. General Considerations ....................................................................................................................... 31.1. Waspmote Libraries .....................................................................................................................................................................3

1.1.1. Waspmote Interruptions Files ..................................................................................................................................31.1.2. Structure ..........................................................................................................................................................................3

2. Architecture ......................................................................................................................................... 3

3. Interruptions subroutines .................................................................................................................. 5

4. Watchdog ............................................................................................................................................. 7

5. RTC ........................................................................................................................................................ 8

6. Accelerometer ...................................................................................................................................... 9

7. Sensors ............................................................................................................................................... 10

8. GSM/GPRS .......................................................................................................................................... 11

9. 3G/GPRS ............................................................................................................................................. 12

10. Critical battery ................................................................................................................................. 13

11. Other functions used by the API .................................................................................................... 1411.1. Attaching interruptions ........................................................................................................................................................1411.2. Detaching interruptions ......................................................................................................................................................1411.3. Enabling interruptions ..........................................................................................................................................................1411.4. Disabling interruptions ........................................................................................................................................................1411.5. Clearing ‘intFlag’ ......................................................................................................................................................................15

12. Code examples and extended information ................................................................................... 16

13. API changelog .................................................................................................................................. 17

14. Documentation changelog ............................................................................................................. 18

Document Version: v4.1 - 04/2013

© Libelium Comunicaciones Distribuidas S.L.

-3- v4.1

General Considerations

1. General Considerations

1.1. Waspmote Libraries

1.1.1. Waspmote Interruptions Files

Winterrupts.c

1.1.2. Structure

The functions used to manage interruptions are stored in ‘Winterrupts.c’. This C file has no header file associated, but the functions are declared in ‘wiring.h’. Since it is a C file, no constructor is needed and no functions declared in other C++ Waspmote libraries can be used, only the libraries developed in C.

2. ArchitectureThe microcontroller receives all types of interruption as hardware interruptions. For this reason the UART1 (RXD1 and TXD1) pins are used.

Waspmote has several interruption sources which can be used:

• Watchdog • RTC • Accelerometer • XBee • 3G/GPRS • Sensors • Critical battery

Figure 1: Interruptions diagram

-4- v4.1

Architecture

The interruption signals from the RTC, accelerometer, 3G/GPRS, XBee and sensors are connected to RXD1 pin. The interruption signal from the critical battery is connected to TXD1 pin, while the internal Watchdog ‘simulates’ a hardware interruption using a reserved digital pin (DIGITAL0). This simulation by the Watchdog has been implemented to maintain the same functionality structure in all the interruption sources and can fill in flags in the same way.

The interruption pin of the modules is connected through a diode to RXD1 or TXD1 in order to avoid interferences between the different interruption sources. Besides, there is a unique monitoring pin for each module. Thus, when the interruption is captured, the monitoring pin of each module is analyzed to see which one generated it.

The definition of the monitoring and interruptions pins can be found in the WaspConstants.h file. The most important definitions are:

WTD_INT: Watchdog interruption

RTC_INT: RTC interruption

ACC_INT: Accelerometer interruption

XBEE_INT: XBee module interruption

UART1_INT: 3G/GPRS interruption

SENS_INT: Sensors interruption

BAT_INT: Critical battery interruption

Because of the multiplexing of these interruption signals, a series of flag vectors have been created in WaspVariables.h to find out the module which generated the interruption. These flags are: intConf, intFlag, and intArray.

intConfThis flags vector is used to set which modules are enabled to generate interruptions. Only interruptions that are previously enabled in this vector will be received.

Figure 2: Structure of the ‘intConf’ flag

intFlagThis flag is used to find out which module generated the captured interruption. This flag marks the position corresponding to the module which generated the interruption.

Figure 3: Structure of the ‘intFlag’ flag

intCounterThis flag is used to count the total number of interruptions which have been produced. Each time an interruption is generated this counter is increased.

intArrayThis flag is used to count the total number of interruptions that have been produced for each module. Each time an interruption is produced the position corresponding to the module which has generated it is increased.

Figure 4: Diagram of the ‘intArray’ flag

-5- v4.1

Interruptions subroutines

3. Interruptions subroutines

Two subroutines defined in Winterruptions.c are associated to the interruption pins:

• onHAIwakeUP (On High Active Interruption). This subroutine is run by the modules which generate high level interruptions (usually in RXD1 pin).

• onLAIwakeUP (On Low Active Interruption). This subroutine is run by the modules which generate low level interruptions (usually in TXD1 pin).

These subroutines check both ‘intConf’ flag and monitoring pin related to each interruption source in order to know what module triggered the interruption. When the two conditions match:

• ‘intFlag’ is activated on the correct position to show the module that provoked the interruption. • ‘intCounter’ is incremented each time an interruption is detected. • ‘intArray’ is incremented in the correct position to know how many times a module has activated the interruption.

Initially no further action is taken, in an attempt to add the minimum time delay possible in the execution trace of the program’s main code. Once these flags are updated we return to the instruction which was being run before capturing the interruption.

It is in the main code where the interruption is treated by the user when the interruption flag is marked in intFlag vector. The aim of this design is to avoid pausing actions that Waspmote may be doing at the moment the interruption triggers, an example would be sending a packet through the XBee radio.

The most useful characteristic of interruptions is to combine them with low power states Waspmote provides. This way, the device enters a low power state until an interruption wakes up Waspmote. The figure below is a simple example:

Figure 5: Process of an interruption

The correct use of the flags allows the chaining of interruptions; as a result, several interruptions can be triggered before treating them. However, because several interruption signals are multiplexed in the same pin, the user must keep in mind that the interruption pin can be masked by different interruption sources. So it could be interesting to deactivate some interruption signal when they occur.

-6- v4.1

Interruptions subroutines

Figure 6: Treatment of chained interruptions

Note: The GPS and 3G/GPRS modules use the UART_1 (RXD1 and TXD1) to establish communication with the microcontroller. So at the moment of communicating with them, the interruptions must be deactivated for the time the process lasts.

-7- v4.1

Watchdog

4. WatchdogThe Watchdog allows the microcontroller to be woken up from a low consumption state by generating an interruption.

This is a software-generated interruption. The interruption generation is different to the other Waspmote modules. To unify the operation with the rest of the modules, a hardware interruption is simulated when receiving the software interruption.

When the Watchdog interruption occurs, an internal subroutine is run to generate the hardware interruption simulation. The reserved DIGITAL0 pin is used to monitor this simulated interruption which is a low active interruption. For this reason, when this interruption occurs, the subroutine onLAIwakeUP is executed, marking the corresponding flags.

The interruption generated by the Watchdog is used to control the Waspmote’s Sleep mode, allowing it to put the mote to sleep during the Watchdog’s alarm cycle. The possibilities are:

WTD_16MS: 16ms

WTD_32MS: 32ms

WTD_64MS: 64ms

WTD_128MS: 128ms

WTD_250MS: 256ms

WTD_500MS: 500ms

WTD_1S: 1s

WTD_2S: 2s

WTD_4S: 4s

WTD_8S: 8s

Figure 7: How to use the Watchdog interruption

The generated interruptions can also be used by the Watchdog as timed alarms without the need for the microcontroller to be in energy saving mode. The Watchdog alarms can be used for time less or equal to 8s. For longer times the RTC must be used.

• Watchdog interruption example:

http://www.libelium.com/development/waspmote/examples/int-01-watchdog-timer-interrupt

Related API libraries: WaspPWR.h, WaspPWR.cpp

All information about their programming and operation can be found in the document: Energy and Power Programming Guide.

All the documentation is located in the Development section in the Libelium website.

-8- v4.1

RTC

5. RTCThe RTC can be used to set a common time base in all the Waspmotes in a network. The DS32321SN allows maximum accuracy without deviations over time, which makes possible to manage a synchronized network. Also, it is useful for sending and receiving tasks to be carried out in the same temporal window. The operating paradigm would be that every ‘x’ seconds the motes would wake up and establish communication between each other enabling data output to the control center.

The RTC is capable of generating cyclical interruptions through 2 alarms which can be configured:

• Alarm 1 can be configured in 1 second cycles • Alarm 2 can be configured for 1 minute cycles.

Both alarms can be used to generate an interruption and wake Waspmote from a low consumption mode.

The RTC generates the high level interruption so the RXD1 pin is used to capture this interruption. It also has a unique monitoring pin. When the interruption occurs in the RXD1 pin, the subroutine ‘onHAIwakeUP’ is run marking the corresponding flags.

The use of the RTC has been associated with Waspmote’s Deep Sleep and Hibernate modes, allowing it to put the microcontroller to sleep, activating alarm 1 in the RTC to wake it. Thus, Waspmote can be put into the lowest consumption mode and woken up using the RTC. For more information about these energy saving modes, consult the Energy and Power Programming Guide.

It is also possible to use the interruptions generated by the RTC as timed alarms without the need for the microcontroller to be in energy saving modes. The use of RTC alarms is recommended for times longer than 8s, since for shorter timers the microcontroller’s internal Watchdog can be used.

Figure 8: RTC alarm operation

• RTC interruption example:

http://www.libelium.com/development/waspmote/examples/int-02-rtc-alarm-interrupt

Related API libraries: WaspRTC.h, WaspRTC.cpp

All information about their programming and operation can be found in the document: RTC Programming Guide.

All the documentation is located in the Development section in the Libelium website.

-9- v4.1

Accelerometer

6. AccelerometerThe Waspmote accelerometer can generate several types of interruption: free fall, inertial wake up, 6D movement and 6D position. To be able to manage all types of interruptions, different functions have been created in order to enable each kind of interruption (only once at a time).

The accelerometer generates a high level interruption, so the RXD1 pin is used to capture this interruption. A single monitoring pin is also used. When the interruption occurs in RXD1, the subroutine onHAIwakeUP is run, marking the corresponding flags.

The alarms are generated in the accelerometer when certain previously defined thresholds are reached. These thresholds determine what is the needed acceleration for triggering the interruption. These thresholds are defined in ‘WaspACC.h’.

Figure 9: Accelerometer interruption operation

• Accelerometer interruption example:

http://www.libelium.com/development/waspmote/examples/int-03-accelerometer-interrupt

Related API libraries: WaspACC.h, WaspACC.cpp

All information about their programming and operation can be found in the document: Accelerometer Programming Guide.

All the documentation is located in the Development section in the Libelium website.

-10- v4.1

Sensors

7. SensorsThe sensors are mainly connected to Waspmote through the microprocessor’s analog and digital inputs. Libelium has developed several sensor integration boards which facilitate their connection with the processing unit. Each one of these sensor boards has several pins used to manage the generation and capture of interruptions. There is a pin which is connected to a microcontroller’s interruption pin and there is another pin used for monitoring.

Figure 10: Sensor board alarm operation

• Sensor Event interruption example:

http://www.libelium.com/development/waspmote/examples/int-05-sensor-event-interrupt

Sensor board interruptions are managed quite differently from the rest of the interruptions, so it is recommended to check the sensor boards technical guides.

All the documentation is located in the Development section in the Libelium website.

-11- v4.1

GSM/GPRS

8. GSM/GPRSThe GSM/GPRS module (SIM900 model from SIMCom) is able of generating interruptions on receiving data from TCP and UDP sockets, calls and SMS.

Because the GSM/GPRS module is connected to the UART_1, it uses the RXD1 and TXD1 pins to send and receive data, so on receiving data, calls or SMS, it generates messages which enable it to generate interruptions.

The GSM/GPRS module generates a low level interruption in the RXD1 pin. This is because the UART idle state is ‘1’ logic level and GPRS module communicating with the microcontroller would cause the RXD1 pin to go down. A single monitoring pin is also used. When the interruption occurs in RXD1, the subroutine onLAIwakeUP is run, marking the corresponding flags.

Figure 11: GSM/GPRS module alarm operation

• GPRS module interruption example:

http://www.libelium.com/development/waspmote/examples/int-04-gprs-pro-interrupt

Related API libraries: WaspGPRS_Pro.h, WaspGPRS_Pro.cpp and WaspGPRS_Proconstants.h

All information about their programming and operation can be found in the document: GSM/GPRS Programming Guide.

All the documentation is located in the Development section in the Libelium website.

-12- v4.1

3G/GPRS

9. 3G/GPRSThe 3G/GPRS module (SIM5218E model from SIMCom) is able to generate interruptions on receiving data from TCP and UDP sockets, calls and SMS.

Because the 3G/GPRS module is connected to the UART_1, it uses the RXD1 and TXD1 pins to send and receive data, so on receiving data, calls or SMS, it generates messages which enable it to generate interruptions.

The 3G/GPRS module generates a low level interruption in the RXD1 pin. This is because the UART idle state is ‘1’ logic level and 3G module communicating with the microcontroller would cause the RXD1 pin to go down. A single monitoring pin is also used. When the interruption occurs in RXD1, the subroutine onLAIwakeUP is run, marking the corresponding flags.

Figure 12: 3G/GPRS module alarm operation

• 3G/GPRS module interruption example:

www.libelium.com/development/waspmote/examples/int-07-3G-interrupt

Related API libraries: Wasp3G.h and Wasp3G.cpp

All information about programming and operation can be found in the document 3G/GPRS Networking Guide.

All the documentation is located in the Development section in the Libelium website.

-13- v4.1

Critical battery

10. Critical batteryWaspmote has a critical battery detector, which generates an interruption when the battery charge drops below a set voltage threshold. This is based on the batteries having a drop in voltage which is accentuated as the charge decreases. For this reason, a decrease in power voltage corresponds to a variation in the remaining charge.

This threshold can be configured dynamically in Waspmote as it is controlled by a digital potentiometer (digipot). The range of values which can be configured for this threshold is from 3.4V to 3.1V.

Digipot resistance (kohm) Voltage (V)

200 3.40

180 3.36

160 3.31

140 3.27

120 3.22

100 3.18

80 3.13

Figure 13: Critical battery control levels

The digipot value can be modified to change the threshold in real time in the same program code which Waspmote is running.

Example of programming a critical battery threshold

{ PWR.setLowBatteryThreshold(3.4); }

The threshold value must be such that when it jumps and enters the interruption treatment routine, it allows communicating with the rest of the brother nodes or the control center through the communication module containing the message ”I am the node ID=5. My battery is running out!” so that the network operators can replace or recharge its battery.

WARNING: As the critical battery detector maintains a low level on the TXD1 pin, while the battery level does not exceed the threshold previously set, it is not possible to re-enable the interruptions related with the TXD1. If they were re-enabled it would be possible to enter into an infinite loop because the microcontroller would always detect the low battery interrupt, as the level is below the threshold.

In systems in which the charge can be recovered (e.g. charging through the solar panel), it is recommended to read the critical battery monitoring pin value every ‘x’ seconds, so that when a change in the value of this pin is detected, passing from low to high level, the interruptions in the TXD1 are activated again.

• Critical battery detection example:

http://www.libelium.com/development/waspmote/examples/int-06-critical-battery-interrupt

RECOMMENDATION: Instead of using this interruption, it is recommended to check the battery level every ‘x’ time in order to put Waspmote to sleep. Besides, the battery level can be periodically checked entering to sleep mode again until it gets over the level the user desires. Thus, it will be possible to recharge the battery via solar panel or other ways.

Related API libraries: WaspPWR.h, WaspPWR.cpp

All information about their programming and operation can be found in the document: Energy and Power Programming Guide.

All the documentation is located in the Development section in the Libelium website.

-14- v4.1

Other functions used by the API

11. Other functions used by the API

11.1. Attaching interruptionsIt attaches the interruption to the corresponding microcontroller pin and subroutine associated to it.

This function returns nothing.

This function is used internally by ‘enableInterrupts’.

Example of use

{ // Attach Interrupt on pin ‘ACC_INT_ACT’ using subroutine ‘onHAIwakeUP’ on ‘HIGH’ level attachInterrupt(ACC_INT_ACT, onHAIwakeUP, HIGH);}

11.2. Detaching interruptionsIt detaches the interruption from the corresponding microcontroller pin.

This function returns nothing.

This function is used internally by ‘disableInterrupts’.

Example of use

{ //Detachesthespecifiedinterruption detachInterrupt(ACC_INT_ACT);}

11.3. Enabling interruptionsIt enables the specified interruption.

When this function is called, ‘intConf’ flag is updated with the new active interruption. After that, it is attached to the corresponding microcontroller pin and associated subroutine.

Example of use

{ //Enablesthespecifiedinterruption enableInterrupts(ACC_INT);}

11.4. Disabling interruptionsIt disables the specified interruption.

When this function is called, ‘intConf’ flag is updated with the interruption that has been detached. After that, it is detached from the corresponding microcontroller pin and associated subroutine.

Example of use

{ //Disablesthespecifiedinterruption disableInterrupts(ACC_INT);}

-15- v4.1

Other functions used by the API

11.5. Clearing ‘intFlag’It clears the global flag ‘intFlag’. It sets intFlag to zero.

Example of use

{ clearIntFlag(); // Clears ‘intFlag’}

-16- v4.1

Code examples and extended information

12. Code examples and extended informationIn the Waspmote Development section you can find complete examples:

http://www.libelium.com/development/waspmote/examples

-17- v4.1

API changelog

13. API changelog

Function / File Changelog Version

onHAIwakeUP Changed function. Added additional comparisons for XBee module and 3G interruptions. Deleted the check for anemometer interruptions. V0.31 → v1.0

onLAIwakeUP Changed function. Added new comparison for UART1 interruption. Deleted pluviometer comparison. V0.31 → v1.0

enableInterrupts Changed interruption attachment for UART1 interruption. Deleted anemometer attachment. Added XBee module and 3G interruption attachment. V0.31 → v1.0

disableInterrupts Deleted anemometer interruption detachment. Added XBee module and 3G module detachment. V0.31 → v1.0

intCounter Changed 'intCounter' to static variable V0.31 → v1.0

intArray Increased intArray to a 14-element array V0.31 → v1.0

-18- v4.1

Documentation changelog

14. Documentation changelogAdded chapter “3G/GPRS”.