Libelium Waspmote 3G Plus GPS Networking Manual

Waspmote 3G + GPS
Networking Guide
-2-
v4.9
Document Version: v4.9 - 06/2015 © Libelium Comunicaciones Distribuidas S.L.
INDEX
1. General Considerations ...................................................................................................................... 6
1.1. Introduction ...................................................................................................................................................................................6
1.2. 3G vs GPRS ......................................................................................................................................................................................7
1.3. Hardware .........................................................................................................................................................................................8
1.4. Waspmote Libraries .................................................................................................................................................................. 10
1.4.1. Waspmote 3G Files .....................................................................................................................................................10
1.4.2. Constructor ...................................................................................................................................................................10
1.4.3. Working Modes ..........................................................................................................................................................10
1.4.4. Library fuses .................................................................................................................................................................11
1.4.5. Debug modes ..............................................................................................................................................................11
1.4.6. Special errors ...............................................................................................................................................................11
2. Initialization ....................................................................................................................................... 12
2.1. Initializing the 3G/GPRS module ......................................................................................................................................... 12
2.2. 3G power modes ....................................................................................................................................................................... 12
2.3. Closing communications with the 3G/GPRS module ................................................................................................. 12
2.4. Switching 3G o ........................................................................................................................................................................ 13
2.5. Checking the GSM connection ............................................................................................................................................ 13
2.6. Setting time and date from RTC ..........................................................................................................................................13
2.7. Setting operator parameters ................................................................................................................................................14
3. SIM related functions ........................................................................................................................ 15
3.1. Setting the PIN ........................................................................................................................................................................... 15
3.2. Changing PIN number.............................................................................................................................................................15
3.3. Getting IMSI ............................................................................................................................................................................... 15
3.4. Getting IMEI ...............................................................................................................................................................................16
4. GSM related functions ....................................................................................................................... 17
4.1. Setting information returned when receiving a call ....................................................................................................17
4.2. Making calls ................................................................................................................................................................................ 17
4.3. Making lost calls ....................................................................................................................................................................... 17
4.4. Hanging up calls ........................................................................................................................................................................ 18
4.5. Setting CLI presentation in incoming calls ...................................................................................................................... 18
4.6. Setting CLI restriction in outcoming calls ........................................................................................................................ 18
4.7. Gets the phone activity status .............................................................................................................................................. 19
4.8. Autoanswer ................................................................................................................................................................................. 19
4.9. Answer a call ............................................................................................................................................................................... 19
4.10. Generating DTMF tones ....................................................................................................................................................... 20
4.11. Ringer level ............................................................................................................................................................................... 21
-3-
v4.9
4.12. Setting Information returned when receiving an SMS ............................................................................................. 21
4.13. Setting Mode for SMS ........................................................................................................................................................... 21
4.14. Sending SMS ............................................................................................................................................................................ 22
4.15. Getting the number of SMS stored in SIM card ........................................................................................................... 22
4.16. Deleting SMS ............................................................................................................................................................................ 22
5. File system related functions ............................................................................................................ 23
5.1. Description .................................................................................................................................................................................. 23
5.2. Go to the root directory of desired unit ............................................................................................................................23
5.3. Changing directory .................................................................................................................................................................. 23
5.4. Getting le size ..........................................................................................................................................................................24
5.5. Deleting les ............................................................................................................................................................................... 24
5.6. MicroSD is present .................................................................................................................................................................... 24
5.7. List subdirectories/les in current directory ................................................................................................................... 25
5.8. Getting les from 3G/GPRS to Waspmote ........................................................................................................................ 25
6. Camera related functions .................................................................................................................. 26
6.1. Connecting the camera .......................................................................................................................................................... 26
6.2. Starting the camera ..................................................................................................................................................................26
6.3. Stopping the camera ............................................................................................................................................................... 27
6.4. Conguration of the camera ................................................................................................................................................. 27
6.4.1. Resolution .....................................................................................................................................................................27
6.4.2. Brightness .....................................................................................................................................................................28
6.4.3. Rotation .........................................................................................................................................................................28
6.4.4. FPS ...................................................................................................................................................................................29
6.4.5. Picture name ................................................................................................................................................................29
6.4.6. Adding time stamp on pictures ............................................................................................................................29
6.5. Taking pictures ........................................................................................................................................................................... 30
6.6. Recording videos ......................................................................................................................................................................30
6.7. Making videocalls ..................................................................................................................................................................... 31
6.8. Setting the video quality ........................................................................................................................................................ 32
6.9. Sending DMTF tones ...............................................................................................................................................................32
7. FTP and FTPS ...................................................................................................................................... 33
7.1. Creating your own FTP server ..............................................................................................................................................33
7.2. FTP related functions ............................................................................................................................................................... 34
7.2.1. Setting FTP parameters ............................................................................................................................................34
7.2.2. Uploading les from Waspmote ...........................................................................................................................35
7.2.3. Uploading les from 3G/GPRS module ..............................................................................................................35
7.2.4. Downloading les to Waspmote ..........................................................................................................................36
7.2.5. Downloading les to 3G/GPRS module .............................................................................................................36
7.3. FTPS related functions ............................................................................................................................................................37
7.3.1. Log into FTPS server ..................................................................................................................................................37
7.3.2. Uploading les from Waspmote ...........................................................................................................................37
7.3.3. Uploading les from 3G/GPRS module ..............................................................................................................38
-4-
v4.9
7.3.4. Downloading les to Waspmote ..........................................................................................................................38
7.3.5. Downloading les to 3G/GPRS module .............................................................................................................39
7.3.6. Log out the FTPS server ...........................................................................................................................................39
8. SMTP and POP3 related functions.................................................................................................... 40
8.1. Sending email with SMTP ...................................................................................................................................................... 40
8.1.1. Setting the SMTP server ...........................................................................................................................................40
8.1.2. Setting the sender address and name ................................................................................................................40
8.1.3. Setting the recipient address and name ............................................................................................................40
8.1.4. Setting the subject and the body.........................................................................................................................41
8.1.5. Attaching les ..............................................................................................................................................................41
8.1.6. Sending the email ......................................................................................................................................................41
8.2. Receiving emails with POP3 .................................................................................................................................................. 42
8.2.1. Setting the POP3 server parameters ...................................................................................................................42
8.2.2. Getting a list of emails ..............................................................................................................................................42
8.2.3. Getting the header of an email .............................................................................................................................42
8.2.4. Getting an email .........................................................................................................................................................43
8.2.5. Deleting an email .......................................................................................................................................................43
9. HTTP and HTTPS ................................................................................................................................ 44
9.1. HTTP connections ..................................................................................................................................................................... 44
9.1.1. GET method .................................................................................................................................................................44
9.1.2. POST method ...............................................................................................................................................................44
9.1.3. Server response ..........................................................................................................................................................45
9.2. Reading an URL ..........................................................................................................................................................................45
9.3. Sending a frame to Meshlium .............................................................................................................................................. 46
9.4. HTTPS connections .................................................................................................................................................................. 47
9.4.1. HTTPS function ...........................................................................................................................................................48
10. GPS .................................................................................................................................................... 49
10.1. Dierences between GPS modes .....................................................................................................................................49
10.2. Technical data from the GPS receiver .............................................................................................................................. 49
10.3. Starting GPS .............................................................................................................................................................................. 50
10.4. Stopping the GPS ...................................................................................................................................................................51
10.5. Managing GPS data ............................................................................................................................................................... 51
11. TCP and UDP connections ............................................................................................................... 53
11.1. Conguration of the 3G/GPRS module for TCP and UDP ......................................................................................... 53
11.2. Getting the IP assigned to the module ...........................................................................................................................54
11.3. Query a IP address from a domain name .......................................................................................................................54
11.4. Query a domain name from a IP address .......................................................................................................................55
11.5. Working in single client mode ........................................................................................................................................... 55
11.5.1. Creating a socket .....................................................................................................................................................55
11.5.2. Sending and receiving data .................................................................................................................................56
11.5.3. Closing the socket ...................................................................................................................................................56
-5-
v4.9
11.6. Working in multi client mode.............................................................................................................................................56
11.6.1. Enable the multi client mode ..............................................................................................................................57
11.6.2. Creating sockets .......................................................................................................................................................57
11.6.3. Sending and receiving data .................................................................................................................................57
11.6.4. Closing the socket ...................................................................................................................................................58
11.7. Working in TCP server mode ..............................................................................................................................................58
11.7.1. Creating the server ..................................................................................................................................................58
11.7.2. Listing the clients .....................................................................................................................................................59
11.7.3. Activate a client ........................................................................................................................................................59
11.7.4. Sending and receiving data .................................................................................................................................59
11.7.5. Disconnecting a client ...........................................................................................................................................60
11.7.6. Closing the server ....................................................................................................................................................60
12. Miscellaneous functions ................................................................................................................. 61
12.1. Managing incoming data .................................................................................................................................................... 61
12.2. Getting RSSI level ....................................................................................................................................................................61
12.3. Getting cell system information ........................................................................................................................................ 61
12.4. Getting cell channel information ..................................................................................................................................... 62
12.5. Getting serving cell radio parameters ............................................................................................................................63
12.6. Setting preferred service domain ..................................................................................................................................... 63
12.7. Scanning the network band channels ............................................................................................................................ 64
12.8. Getting UE system information ......................................................................................................................................... 65
12.9. Show network system mode .............................................................................................................................................. 66
12.10. Shows system information in WCDMA .........................................................................................................................66
12.11. Setting network system mode preference .................................................................................................................67
12.12. Setting the preferences for order of acquisitions .....................................................................................................67
12.13. Choosing the storage location ........................................................................................................................................ 68
12.14. Changing the baudrate ......................................................................................................................................................68
12.15. Sending AT commands to the 3G/GPRS module .....................................................................................................68
12.16. Choosing audio output ......................................................................................................................................................69
12.17. Setting the gain level of the microphone ................................................................................................................... 69
12.18. Setting the loudspeaker volume .................................................................................................................................... 69
12.19. Getting module information ...........................................................................................................................................70
13. Geolocation tracker application example ..................................................................................... 71
14. API changelog .................................................................................................................................. 74
15. Documentation changelog ............................................................................................................. 75
Apendix A. CME error codes ................................................................................................................. 76
Apendix B. CMS error codes .................................................................................................................. 77
-6-
v4.9
General Considerations
1. General Considerations
1.1. Introduction
The 3G/GPRS module for Waspmote allows sensor networks and M2M devices to connect to the Cloud by using high speed WCDMA and HSPA cellular networks in the same way as Smartphones do. This makes possible sensor nodes send not only discrete sensor information such as temperature or humidity (which can be encoded using just a single number) but also complex streams of information such as photos and videos. This feature allows developers the creation of new Smart Security applications.
The 3G/GPRS module for the Waspmote sensor platform oers speed rates of 7.2Mbps in download mode and 5.5Mbps when uploading information to the Cloud. This is a incredible increase compared with previous cellular technologies such as GPRS we rates were of 0.02Mbps and 0.01Mbps respectively.
Each Waspmote sensor node may integrate at the same time a medium range radio such as 802.15.4/ZigBee/Bluetooth/WiFi and one long range 3G radio. This way we can minimize costs by using the mobile network just when really needed.
The module counts also with an internal GPS what enables the location of the device outdoors and indoors combining standard NMEA frames with mobile cell ID triangulation using both assisted-mobile (A-GPS) and mobile-based (S-GPS) modes.
The 3G communicating module is specially oriented to work with Internet servers implementing internally several application layer protocols which make easier to send the information to the cloud. We can make HTTP and HTTPS (secure mode) navigation, downloading and uploading content to a web server. In the same way FTP and FTPS (secure mode) protocols are also available, which is really useful when your application requires handling les. You can even send and receive mails directly from Waspmote using the SMTP and POP3 clients implemented internally.
Coinciding with the release of the 3G/GPRS module and in order to take part of all the the capabilities Libelium launched the Video Camera Sensor board, which allows to each of the nodes of the sensor network to take photos (640x480), record videos (320x240) and upload them in real time to the Cloud. The Video Camera Sensor board includes 22 high power IR LED’s to implement a night vision mode.
The 3G/GPRS module comes with an internal SD Card of 2GB (extended up to 32GB) which is used to store the photos and videos taken by the Video Camera Sensor Board without the need of being handled by the MCU. This ensures we get real speed ranges (7.2Mbps download and 5.5Mbps upload) as the communication is direct between the SD and the 3G/GPRS module.
The GPS module also makes possible perform geolocation services even indoors as it can work in A-GPS and S-GPS modes, so the location given by the GPS through NMEA sentences is completed with the cell information provided by both the 3G/GPRS module and external Internet Geoposition Servers such as the ones oered by Google which helps you to get the most accurate location in real time.
-7-
v4.9
General Considerations
1.2. 3G vs GPRS
Comparative table between the 3G and the GPRS module for Waspmote:
Model 3G (SIM5218) GPRS (SIM900) GPRS+GPS (SIM928)
Download speed 7.2Mbps 0.02Mbps 0.02Mbps
Upload speed 5.5Mbps 0.01Mbps 0.01Mbps
FTP Yes Yes Yes
FTPS (Secure) Yes No No
HTTP Yes Yes Yes
HTTPS (Secure) Yes No No
TCP/UDP Sockets Yes Yes Yes
Mails Yes No No
GPS Yes (A-GPS + S-GPS + NMEA) No Yes, but only NMEA stand-
alone mode
Video Camera Yes (Photo + Video) No No
Video Calls Yes No No
Protocols 3G, WCDMA, HSPA, UMTS, GPRS, GSM GPRS/GSM GPRS/GSM
Frequency Bands 850, 900, 1800, 1900, 2100MHz 850, 900, 1800, 1900MHz 850, 900, 1800,1900MHz
SD Card Yes (up to 32GB) No No
Figure: Comparative table between 3G/GPRS module, GPRS and GPRS+GPS module.
-8-
v4.9
General Considerations
1.3. Hardware
GSM / GPRS / 3G module
Figure: 3G/GPRS board
Model: SIM5218E (SIMCom)
Tri-Band UMTS 2100/1900/900MHz
Quad-Band GSM/EDGE, 850/900/1800/1900 MHz
HSDPA up to 7.2Mbps
HSUPA up to 5.76Mbps
TX Power:
- UMTS 900/1900/2100 0,25W
- GSM 850MHz/900MHz 2W
- DCS1800MHz/PCS1900MHz 1W
Sensitivity: -106dBm
Antenna connector: UFL
External Antenna: 0dBi
Consumption in sleep mode: 1mA
Dimensions (3G/GPRS module): 33 x 62 x 12 mm
Dimensions (3G/GPRS module plugged on Waspmote): 73 x 62 x 20 mm
Note for USA users: We have tested the new 3G shield with the AT&T network which supports nativelly the GSM and 3G protocolos. With other carriers may also work although we haven’t tried and thus we can not ensure it. For this reason we recommend to use AT&T SIM cards.
-9-
v4.9
General Considerations
Actions:
Videocall, record video and take pictures available with Video Camera Sensor Board
Support microSD card up to 32GB
64MB of internal storage space
Making/Receiving calls
Making ‘x’ tone missed calls
MS-assisted (A-GPS), MS-based (S-GPS) or Stand-alone GPS positioning
Sending/Receiving SMS
Single connection and multiple connections TCP/IP and UDP/IP clients
TCP/IP server.
HTTP and HTTPS service
FTP and FTPS Service (downloading and uploading les)
Sending/receiving email (SMTP and POP3)
OTA feature can be performed now by Waspmote’s 3G/GPRS module. Refer to the Over the Air Programming Guide for more information:
http://www.libelium.com/development/waspmote/documentation/over-the-air-programming-guide-otap/
Figure: 3G/GPRS board in Waspmote
Figure: 3G/GPRS board top
-10-
v4.9
General Considerations
Figure: 3G/GPRS board bottom
1.4. Waspmote Libraries
1.4.1. Waspmote 3G Files
Wasp3G.h ; Wasp3G.cpp
1.4.2. Constructor
In order to start using Waspmote 3G library, an object from class ‘Wasp3G’ must be created. This object, called ‘_3G’, is created inside Waspmote 3G library and it is public to all libraries. It is used throughout the guide to show how the Waspmote 3G library works.
When creating this constructor, some variables are dened with a value by default, that can be modied later. These variables are:
_baudRate : species the baudrate used to communicate with the module (115200 by default).
_socket : species the socket used to communicate with the module (socket1 by default).
_pwrMode : species the power mode (_3G_ON by default).
1.4.3. Working Modes
Some constants have been dened to set the dierent working modes for the 3G/GPRS module.
1: _3G_ON. Module is powered on. Starts the module in full functionality.
2: _3G_FULL. Module is set in full functionality (power consumption around 50mA with peaks around 1-1’4A).
3: _3G_MINIMUM. Module deactivates RF and SIM (power consumption around 35mA).
4: _3G_RF_OFF. Module deactivates RF (power consumption around 35mA).
5: _3G_SLEEP. In this mode the 3G/GPRS module deactivates RF and SIM and enters in sleep mode when the when the periphery equipment stops working. The power consumption in this state is around 1mA.
0: _3G_OFF. Module is powered o. Supply from the battery are disconnected by the transistors.
When the module communicates with carrier, current peaks between 1-1’4A are produced.
-11-
v4.9
General Considerations
1.4.4. Library fuses
The library for this module is divided in 9 sections and other section with functions and constants that always are active. Each section is activated/deactivated by a fuse. This fuses are located in Wasp3G.h. By default this fuses have a ‘1’ allowing to use the functions. The Wasp3G.h have this fuses:
GSM_FUSE: Call and SMS related funtions and constants
CAMERA_FUSE: Camera related funtions and constants
FTP_FUSE: FTP related funtions and constants
MAIL_FUSE: SMTP and POP3 related funtions and constants
HTTP_FUSE: HTTP and HTTPS related funtions and constants
GPS_FUSE: GPS related funtions and constants
IP_FUSE: TCP and UDP related funtions and constants
TRANSMISION_FUSE: File transmission related funtions and constants
OTA_FUSE: OTA related funtions and constants (FTP_FUSE must be ‘1’ too)
For deactivate a section change the ‘1’ in the related fuse by ‘0’.
Note: If you use a function with the related fused with a value of ‘0’, the compiler will give you an error. Please, be carefully when you use the fuses.
Note: If you do not use the Videocamera Board, switch the Videocamera fuse to 0.
1.4.5. Debug modes
The library have two debug modes implemented that allows to the experimented user show the data transmitted and received between the Waspmote and the 3G/GPRS module. The value of the _3G_debug_mode constant selects the debug mode:
‘0’ Disables all debug messages
‘1’ Shows only the commands sent to the 3G/GPRS module and some extra messages
‘2’ Shows commands sent to the 3G/GPRS module, the data answered by the module and some extra messages
The constant _3G_debug_mode is located in Wasp3G.h le.
1.4.6. Special errors
Some functions can give an extra error code (CME or CMS error codes). This code is stored on _3G.CME_CMS_code. To know the description of the code see the appendix.
-12-
v4.9
Initialization
2. Initialization
2.1. Initializing the 3G/GPRS module
The 3G/GPRS module is connected to a multiplexer, since it is connected to the same microcontroller UART. To start using the 3G/GPRS module, this multiplexer must be switched on and choose the correct combination for the 3G to be selected. This selection is (1,1).
To open the UART and set the multiplexer to the correct combination, a function has been developed. This function powers on (_3G.setMode(_3G_ON)) the module too, but doesn’t congure the UART.
Example of use:
{
// Congures the Waspmote to work with 3G module and starts it:
_3G.ON(); }
2.2. 3G power modes
The 3G/GPRS module has ve dierent power modes: _3G_ON, _3G_FULL, _3G_MINIMUM, _3G_OFFLINE, _3G_SLEEP and _3G_
OFF.
The function setMode will set up the ‘pwrMode’ variable to one of the ve values, but also congures the Waspmote’s pins and sends the serial command to the 3G/GPRS module. It returns ‘1’ on success, ‘0’ and ‘-2’ if error and ‘-3’ when the module starts succesfully with low battery (in which case the user should expect future failures due to not enough power).
The function getMode() gets the power mode of the module.
Example of use:
{
uint8_t powerMode=0; // Sets the 3G in full functionality:
_3G.setMode(_3G_FULL);
// Get _3G power mode: powerMode=_3G.getMode ();
}
Related variables _3G.pwrMode stores 3G power mode
2.3. Closing communications with the 3G/GPRS module
It closes the UART to which the 3G/GPRS module is connected. It means disconnecting the internal UART drivers inside the ATMEGA1281 processor, but the power mode of the 3G/GPRS module don’t change.
Example of use:
{
// Closes UART: _3G.close();
}
-13-
v4.9
Initialization
2.4. Switching 3G o
It closes the UART to which the 3G/GPRS module is connected to and turns it o.
Example of use:
{
// Closes UART and turns it off:
_3G.OFF(); }
2.5. Checking the GSM connection
It checks if the module is connected to the network for a time desired by the input parameter.
If the 3G/GPRS module does not connect within these attempts, function exits with ‘0’.
Example of use:
{
// Waits 60 seconds for connection: _3G.check(60);
}
This function returns:
‘1’ if the module is connected to the carrier
‘0’ if not connected
According to Libelium experience, 60 seconds is the recommended timeout for connecting the 3G/GPRS network. The timeout may vary depending on the network range and quality of service. If the user detects this timeout does not allow his 3G/GPRS to connect, he can experiment with higher values. 120 seconds would be the maximum advised timeout: if the 3G/ GPRS module cannot connect in 2 minutes, it is better to stop trying and check again in the next loop.
Note for USA users: We have tested the new 3G shield with the AT&T network which supports nativelly the GSM and 3G protocols. With other carriers may also work although we haven’t tried and thus we can not ensure it. For this reason we recommend to use AT&T SIM cards.
2.6. Setting time and date from RTC
This function updates the time and the date of the 3G/GPRS module from the RTC.
Example of use:
{
// Updates time and date: _3G.setTime();
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with CME error response
-14-
v4.9
Initialization
2.7. Setting operator parameters
When the 3G module uses some services like IP connections (TCP/UDP), HTTP services, SMTP/POP3 or FTP transfers, it’s mandatory to congure operator parameters like APN, login and password.
There are two ways to congure these settings. The rst one is to use the denitions into the le Wasp3G.h.
#dene _3G_APN “apn” #dene _3G_LOGIN “login” #dene _3G_PASSW “password”
The second one is to use the function set_APN().
Example of use:
{
// If only APN is necessary _3G.set_APN(“provider_APN”); // If APN, login and password are necessary _3G.set_APN(“provider_APN”, “login”, “password”);
}
-15-
v4.9
SIM related functions
3. SIM related functions
Some functions have been developed to congure some settings related with GSM, specically with managing calls and SMS.
3.1. Setting the PIN
It sets the PIN to the SIM card.
Example of use:
{
// Sets PIN=1234 to the SIM: _3G.setPIN(“1234”);
}
This function returns:
‘1’ on success
‘0’ if error
3.2. Changing PIN number
It changes PIN number of SIM card.
Example of use:
{
// Changes the PIN number from “1234” to “4321”: _3G.changePIN(“1234”, “4321”);
}
This function returns:
‘1’ on success
‘0’ if error
‘-1’ if CME code are available
3.3. Getting IMSI
It gets the IMSI from the SIM card and it stores the IMSI into buffer_3G variable.
Example of use:
{ _3G.getIMSI(); }
This function returns:
‘1’ on success
‘0’ if error
-16-
v4.9
SIM related functions
3.4. Getting IMEI
It gets the IMEI from the SIM card and it stores the IMEI into buffer_3G variable.
Example of use:
{ _3G.getIMEI(); }
This function returns:
‘1’ on success
‘0’ if error
-17-
v4.9
GSM related functions
4. GSM related functions
The fuse GSM_FUSE is used to activate or deactivate the functions of this section. If you use a function of this section the fuse must be at ‘1’.
4.1. Setting information returned when receiving a call
This function congures the information returned by the module when a call is received. It is useful to generate interruptions or to store data from the incoming call.
Example of use:
{
// Sets information returned by the module when incoming call: _3G.setInfoIncomingCall();
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with CME error code available
4.2. Making calls
It makes a call to the given telephone number.
Note: the number can be using the country code or only the phone number.
Example of use:
{
// Makes a call to the desired number: _3G.makeCall(“*********”);
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if no carrier
4.3. Making lost calls
It makes a specied duration lost call to the given telephone number.
Note 1: the calling time includes the time to send the request to the carrier, so the receiving call time is a bit shorter than the input parameter.
Note 2: the number can be using the country code or only the phone number.
Example of use:
{
// Makes a lost call of 10 seconds to the desired number: _3G.makeLostCall(“*********”,10);
}
-18-
v4.9
GSM related functions
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if no carrier
4.4. Hanging up calls
It hangs up all the active calls.
Example of use:
{
// Hangs all the active calls up: _3G.hangUp();
}
This function returns:
‘1’ on success
‘0’ if error
4.5. Setting CLI presentation in incoming calls
This function enables or disables the presentation of the incoming call.
Example of use:
{
_3G.setCLIPresentation(ENABLE);
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with CME error code available
4.6. Setting CLI restriction in outcoming calls
This function restricts or enables the presentation of the CLI to the called party when originating a call. Allowed modes
DEFAULT_CLIR, INVOKE_CLIR or SUPPRESS_CLIR.
Example of use:
{
// Restricts the CLI for called party: _3G.setCLIRestriction(SUPPRESS_CLIR);
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with CME error code available
-19-
v4.9
GSM related functions
4.7. Gets the phone activity status
This function gets the phone activity status.
Example of use:
{
uint8_t status=0; // Stores in ‘status’ the state of the phone: status=_3G.getPhoneActStatus();
}
This function returns:
‘0’ for error
‘1’= Ready
‘2’= Unknown
‘3’= Ringing
‘4’= Call in progress
4.8. Autoanswer
This function enables or disables the auto-answer function of the 3G/GPRS module. The function wait a number of “rings” and the answer the call. If the number of rings is 0, disables the autoanswer.
Example of use:
{
// Enables autoanswer for wait 2 rings: _3G.autoAnswer(2);
}
This function returns:
‘1’ on success
‘0’ if error
4.9. Answer a call
This function answers an incoming call.
Example of use:
{
// Answers an incomming call: _3G.answerCall();
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if there isn’t an incoming call
-20-
v4.9
GSM related functions
4.10. Generating DTMF tones
This function generate a DTMF tone according the code listed below:
‘0’ - Stop the sound tone
‘1’ - DTMF tone for 1 key, duration 100ms
‘2’ - DTMF tone for 2 key, duration 100ms
‘3’ - DTMF tone for 3 key, duration 100ms
‘4’ - DTMF tone for 4 key, duration 100ms
‘5’ - DTMF tone for 5 key, duration 100ms
‘6’ - DTMF tone for 6 key, duration 100ms
‘7’ - DTMF tone for 7 key, duration 100ms
‘8’ - DTMF tone for 8 key, duration 100ms
‘9’ - DTMF tone for 9 key, duration 100ms
‘10’ - DTMF tone for 0 key, duration 100ms
‘11’ - DTMF tone for A key, duration 100ms
‘12’ - DTMF tone for B key, duration 100ms
‘13’ - DTMF tone for C key, duration 100ms
‘14’ - DTMF tone for D key, duration 100ms
‘15’ - DTMF tone for # key, duration 100ms
‘16’ - DTMF tone for * key, duration 100ms
‘17’ - Subscriber busy sound, duration always
‘18’ - Congestion sound, duration always
‘19’ - Error information sound, duration 1330*3ms
‘20’ - Number unobtainable sound, duration 1330*3ms
‘21’ - Authentication failure sound, duration 1330*3ms
‘22’ - Radio path acknowledgement sound, duration 700*1ms
‘23’ - Radio path not available sound, duration 400*4ms
‘24’ - CEPT call waiting sound, duration 4000*2ms
‘25’ - CEPT ringing sound, duration always
‘26’ - CEPT dial tone, duration always
Example of use:
{
// Generate subscriber busy sound: _3G.generateTone(17); delay(5000); // Stops the sound: _3G.generateTone(0);
}
This function returns:
‘1’ on success
‘0’ if error
-21-
v4.9
GSM related functions
4.11. Ringer level
This function controls the ringer level of the loudspeaker for incoming call alert. Allowed values: ‘0’ for mute and ‘1’ to ‘5’ for volume level.
Example of use:
{
// Answers an incomming call: _3G.ringerLevel(4);
}
This function returns:
‘1’ on success
‘0’ if error
4.12. Setting Information returned when receiving an SMS
This function congures the information returned by the module when an SMS is received. It is useful to generate interruptions or to store data from the incoming SMS.
Example of use:
{
//Sets information returned by the module when incoming SMS _3G.setInfoIncomingSMS();
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with CMS error code available
‘-3’ if error setting the memory
‘-4’ if error setting the memory with CMS error code available
4.13. Setting Mode for SMS
It sets the text mode for the SMS.
Example of use:
{
//Sets text mode for sms:
_3G.setTextModeSMS(); }
This function returns:
‘1’ on success
‘0’ if error
-22-
v4.9
GSM related functions
4.14. Sending SMS
It sends an SMS to the specied number.
Note: the maximum length is 160 Bytes (160 characters).
Example of use:
{
// Sends this text in a SMS to the desired number _3G.sendSMS(“Hello World!”,“6********”);
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with CMS error code available
4.15. Getting the number of SMS stored in SIM card
This function gets the number of total SMS stored in the SIM card.
Example of use:
{
uint8_t total_SMS=0; // Gets the total SMS in SIM card: total_SMS=_3G.getTotalSMS();
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with CMS error code available
4.16. Deleting SMS
This function deletes an SMS stored in the SIM card. It’s advisable use rst the function getTotalSMS() in order to know the number of SMS.
Example of use:
{
// Deletes the SMS in the 2 index: total_SMS=_3G.getTotalSMS();
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with CMS error code available
-23-
v4.9
File system related functions
5. File system related functions
5.1. Description
The le system is used to store les in a hierarchical (tree) structure, and there are some denitions and conventions to use the Module.
Local storage space is mapped to “C:”, and storage space of present storage card is mapped to “D:”. In both “C:” and “D:” directories, module creates four directories named “Picture”, “Audio”, “Video” and “VideoCall” automatically; “Picture” is used to store static image when taking picture by camera, “Audio” is used to store audio le, “Video” is used to store video le when recording by camera, and “VideoCall” is used to store media le which is recorded during a video call.
The size of the C: unit is 64MB. The microSD card store up to32GBof information.
Some functions have been developed to work with this le system.
5.2. Go to the root directory of desired unit
The function goRoot(unit) selects the ‘unit’ to work (‘0’ for C: unit and ‘1’ for D:), not for save the les created by the module, and goes to the root directory (C: or D:).
Example of use:
{
// changes to microSD card and goes to the root _3G.goRoot(1);
}
This function returns:
‘1’ on success
‘0’ if error
5.3. Changing directory
It changes the directory in the working unit to the directory given as a parameter.
Example of use:
{
// changes to “Picture” directory _3G.cd(“Picture”);
}
This function returns:
‘1’ on success
‘0’ if error
-24-
v4.9
File system related functions
5.4. Getting le size
It gets the size of a le given as a parameter in the current directory.
Example of use:
{
int32_t sizeFile; // gets the size of “le.txt” sizeFile= _3G.getFileSize(“le.txt”);
}
This function returns:
The size of the le
‘-2’ if error
5.5. Deleting les
It deletes a le in the current directory.
Example of use:
{
// deletes “le.txt” _3G.del(“le.txt”);
}
This function returns:
‘1’ on success
‘0’ if error
5.6. MicroSD is present
It checks if the microSD card is present.
Example of use:
{
uint8_t present; // checks if microSD is present present=SD.isSD() ;
}
This function returns:
‘1’ if is present
‘’0’ if not present
-25-
v4.9
File system related functions
5.7. List subdirectories/les in current directory
ls(type_of_ls) stores in buffer_3G a list of the les and/or subdirectories in the current directory. The function needs
a number as input parameter that indicates the kind of the list to do. ‘0’ for list the directories and the les, ‘1’ for list only subdirectories and ‘2’ for list only les.
Example of use:
{
// lists the les in the current directory: _3G.ls(2);
}
This function returns:
‘1’ on success
‘0’ if error
‘2’ if no data
5.8. Getting les from 3G/GPRS to Waspmote
The function getXModemFile(‘origin_le’, ‘destiny_path’) allows to get les from the current directory of the 3G/ GPRS Board and saves it in Waspmote’s microSD card. ‘origin_le’ is the name of the le to get. destiny_path is the path with the name to store the le in Waspmote’s microSD card.
Example of use:
{
// Gets the test1.txt from 3G/GPRS board and stores it in /dir1/t001.txt: _3G.getXModemFile(“test.txt”, “/dir1/t001.txt”);
}
This function returns:
‘1’ if success
‘0’ if error
‘-2’ if error going to root directory in Waspmote’s SD
‘-3’ if error creating the le in Waspmote
‘-4’ if error if le not exist in 3G/GPRS module
‘-5’ if error getting the le
-26-
v4.9
Camera related functions
6. Camera related functions
Waspmote 3G/GPRS module is capable to take pictures and videos and store in the memory of the module or in its external microSD card. To use camera functions the Videocamera Sensor Board is required. This board, the 3G/GPRS Board, allows to Waspmote take pictures in jpg format with a resolution up to VGA quality (640 x 480) and record video in mp4 format with a resolution up to QVGA quality (320 x 240).
Figure: Video Camera Sensor Board
The Video Camera Sensor Board uses 22 IR LEDs to give extra illumination and record with few light or in the night. To eliminate the IR distortion when the board is used with natural light, the board has a lter exchanger with a IR light lter. The board has two sockets for a luminosity sensor and a IR sensor. With the information of these sensors the users can select the proper lter and, if is necessary, to use the IR LEDs.
The Video Camera Sensor Board also includes a presence sensor (PIR), to generate an interruption on Waspmote and take a picture or record a video when a person passes by, this feature is specially designed for security and surveillance applications.
Note: If you use the Videocamera Board, switch the Videocamera fuse to 1.
6.1. Connecting the camera
To connect the Videocamera Sensor Board to the Waspmote 3G board, refer to Videocamera Sensor Guide.
6.2. Starting the camera
The camera must be started before the use. To start the camera use the function startCamera().
Example of use:
{
// Starts the camera:
_3G.startCamera(); }
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if camera not detected
‘-3’ if camera is already started.
-27-
v4.9
Camera related functions
6.3. Stopping the camera
When do not use the camera, the function stopCamera() stops and turns o the camera reducing the power consumption.
Example of use:
{
// Stops the camera:
_3G.stopCamera(); }
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if camera not started
6.4. Conguration of the camera
The camera can be congured in some parameters. Each one have its own function.
Note: the camera must be started to start the conguration.
6.4.1. Resolution
The camera can be congured with 6 dierent resolutions. The next table shows the resolution, the number of horizontal and vertical pixels and the library parameter to use with the function.
Resolution H x V (pixels) library parameter
STAMP 80x48 0
QQVGA 160x120 1
QCIF 176x144 2
QVGA 320x240 3
CIF 352x288 4
VGA 640x480 5
Figure: Resolutions and library parameters
The highest resolution for pictures are VGA (5) and for videos are QVGA (3).
Example of use:
{
// Sets QVGA resolution _3G.cameraResolution(3);
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if camera not detected
‘-3’ if camera not started
-28-
v4.9
Camera related functions
6.4.2. Brightness
The camera have seven levels of brightness, from 0 to 6 (0 is the lowest, 6 is the highest).
Example of use:
{
// Sets highest brightness _3G.cameraBrightness(6);
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if camera not started
‘-3’ if camera is in invalid state
6.4.3. Rotation
The image of the camera can be rotated in steps of 90 degrees: 0, 90, 180 and 270.
Example of use:
{
// Rotates the camera 90 degrees _3G.cameraRotation(“90”);
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if camera not started
‘-3’ if camera is in invalid state
Figure: Video Camera Sensor Board with 0º rotation
-29-
v4.9
Camera related functions
6.4.4. FPS
For record a video 3 dierent FPS can be selected. The parameters are ‘0’ for 7.5 FPS, ‘1’ for 10 FPS and ‘2’ for 15 FPS
Example of use:
{
// Selects 15 fps _3G.cameraFPS(2);
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if camera not started
‘-3’ if camera is in invalid state
6.4.5. Picture name
The name of the pictures can be customized by the user. The name can have up to 20 characters. The name is only a part of the whole name; the whole name is namexxxx.jpg where xxxx is an index of the picture after user dened name.
Example of use:
{
// Sets the name of the pictures // The nal name is → Test_name_xxxx.jpg _3G.pictureName(“Test_name_”);
}
This function returns:
‘1’ on success
‘0’ if error
6.4.6. Adding time stamp on pictures
The function pictureTimeStamp() allows to add a time stamp with the date and time of the 3G/GPRS module.
Example of use:
{
// Adds time stamp _3G.pictureTimeStamp(1);
// Don’t add time stamp _3G.pictureTimeStamp(0);
}
This function returns:
‘1’ on success
‘0’ if error
-30-
v4.9
Camera related functions
6.5. Taking pictures
The function takePicture() takes a picture and stores it in the folder “Picture”. To select if store in the module memory or the external microSD card use the function selectStorage().
Example of use:
{
// Takes a picture: _3G.takePicture ();
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if camera not started
‘-3’ if camera is in invalid state
‘-4’ if there isn’t memory enough
6.6. Recording videos
There are 4 functions related with recording a video:
startVideo(). Starts the recording of the video
pauseVideo(). Pauses the recording of the video
resumeVideo(). Resumes the recording of the video
stopVideo(). Stops the recording of the video
Example of use:
{
// Starts the recording: _3G.startVideo();
// Records 15 seconds and pauses: delay(15000); _3G.pauseVideo();
// Waits 5 seconds and resumes the record: delay(5000); _3G.resumeVideo();
// Records 15 seconds and stops: delay(15000); _3G.stopVideo();
}
The function startVideo() returns:
‘1’ on success
‘0’ if error
‘-2’ if camera not started
‘-3’ if camera is in invalid state
‘-4’ if there isn’t memory enough
-31-
v4.9
Camera related functions
The functions pauseVideo(), resumeVideo() and stopVideo() return:
‘1’ on success
‘0’ if error
‘-2’ if camera not started
‘-3’ if camera is in invalid state
6.7. Making videocalls
It makes a videocall to the given telephone number. To do this you can use the function makeVideoCall(phone_number,
record). The input parameter record allow to record the videocall. ‘0’ not record video, ‘1’ only record far-end video, ‘2’ only
record near-end video and ‘3’ record both far-end and near-end, The video les have been saved in the folder VideoCall/
Example of use:
{
// Makes a videocall and record both far-end and near-end: _3G.makeVideoCall(“*********”, 3);
}
This function returns:
‘1’ if success
‘0’ if error
‘-1’ if error connecting to the other party,
‘-2’ if error with setup or the other party hangs the call
‘-3’ if error connecting the videocall
‘-4’ if error recording the call (videocall is active)
To hang a videocall use the function hangVideoCall().
Example of use:
{
// Hangs the active videocall: _3G.hangVideoCall();
}
This function returns:
‘1’ if success
‘0’ if error
-32-
v4.9
Camera related functions
6.8. Setting the video quality
The video quality can be selected with the function VideoCallQuality(VideoQuality). The parameter VideoQuality can be between 5 for 5 for high quality image or 15 for high motion prole.
Note: This function can be used only when videocall is in idle state, and the setting is available until power o.
Example of use:
{
// Sets high quality image: _3G.VideoCallQuality(5);
}
This function returns:
‘1’ if success
‘0’ if error
6.9. Sending DMTF tones
DMTF tones can be sent during a videocall. Allowed tones are 0–9, * and #.
Example of use:
{
// Sends an example string: _3G.VideoCallDMTF(“0123456789*#);
}
This function returns:
‘1’ if success
‘0’ if error
-33-
v4.9
FTP and FTPS
7. FTP and FTPS
7.1. Creating your own FTP server
First, you should get a server. This server will receive your frames and store them. There is no need to purchase a physical server since there a companies that oer remote servers.
Note: The server used by Libelium to realize the upload and download tests is a Pure-FTPD server (www.pureftpd.org) and it is hosted into a OVH server (www.ovh.com). The Pure-FTPD server has the settings by default:
TLS encryption support: Optional
TLS cipher suite: High-Medium + TLSv1
Allow anonymous logins: No
Allow anonymous uploads: No
Maximum load for anonymous downloads: 4
Maximum idle time (minutes): 15
Maximum connections: 50
Maximum connections per IP address: 8
Allow logins with root password: Yes
Broken clients compatibility: No
From Libelium, we recommend the use of this server hosting provider to obtain good results to upload and download les, but we can’t guarantee the perfect performance of the FTP server.
Also, Libelium has tested with Guebs hosting (www.guebs.com) with good results.
Follow the next steps to create your own FTP server using the terminal:
1 - Install the pure-ftpd server:
sudo apt-get install pure-ftpd
2 - Stop the server:
sudo /etc/init.d/pure-ftpd stop
3 - Before creating the user, it is necessary create a directory to stored the received data:
sudo mkdir /home/ftp and inclide a false shell. To check if the shell exist:
sudo more /etc/shells
4 - If it isn’t the line /bin/false, edit the le, for example with vim, and include it:
sudo vim /etc/shells
5 - After creating a new folder to store data, you have to create a group and a user with false shell, because this type of user don’t need a valid shell (more secure), therefore select /bin/false shell for user and /dev/null as directory:
sudo groupadd ftpgroup
sudo useradd -g ftpgroup -d /dev/null -s /bin/false user1
-34-
v4.9
FTP and FTPS
6 - Modify folder permissions:
sudo chown -R user1 /home/ftp
sudo chmod -R 755 /home/ftp
7 - Add the new user to the pure-ftpd database:
sudo pure-pw useradd username -u ftpuser -g ftpgroup -d /home/ftp
Set the user password when it request.
8 - Update the pure-ftpd database:
sudo pure-pw mkdb
9 - When the users are include in the ftp, start the server:
sudo /etc/init.d/pure-ftpd start
Remeber to open the ports in your router. After this, you will be able to receive FTP transmissions on your server. We advise to use FileZilla to visualize and manage your FTP server.
7.2. FTP related functions
7.2.1. Setting FTP parameters
Before to upload and download les from a FTP server, you need to congure the parameters of the FTP server. The parameters in order are: server address (can be an IP address or a domain name), port, user name, password, mode (1 for passive and 0 for proactive) and type (A for ASCII or I for binary).
Example of use:
{
// Setting FTP parameters _3G.congureFTP(“ftp_address”, “ftp_port”, “user_name”, “password”, 1, “I”);
}
This function returns:
‘1’ on success
‘-2’ if error setting the connection parameters (APN)
‘-3’ if error setting the FTP server
‘-4’ if error setting the FTP port
‘-5’ if error setting the FTP mode
‘-6’ if error setting the FTP type
‘-7’ if error setting the user name
‘-8’ if error setting the FTP password
‘-13’ if error setting the FTP server with if CME error available
‘-14’ if error setting the FTP port with CME error available
‘-15’ if error setting the FTP mode with CME error available
‘-16’ if error setting the FTP type with CME error available
‘-17’ if error setting the user name with CME error available
‘-18’ if error setting the FTP password with CME error available
-35-
v4.9
FTP and FTPS
7.2.2. Uploading les from Waspmote
To upload a le from Waspmote’s SD card you can use the function uploadData(SD_origin, FTP_destination). SD_
origin and FTP_destination are strings that contains the complete path with the le name. The strings must be start with
the character ‘/’, for example “/lename” or “/directory/lename”.
Example of use:
{
// Uploading a le from Waspmote _3G.uploadData(“/SD_path/SD_le_name”, “/FTP_path/FTP_le_name”);
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with CME code (FTP error)
‘-3’ if error getting le size from SD
7.2.3. Uploading les from 3G/GPRS module
To upload a le from the SD card of the 3G/GPRS module you can use the function uploadFile(3G_folder, FTP_
destination_path). 3G_folder is a number that indicates the folder that contains the le to upload. Allowed values for 3G_folder:
0 – current directory
1 – “C:/Picture” directory
2 – “C:/Video” directory
3 – “C:/VideoCall” directory
4 – “D:/Picture” directory
5 – “D:/Video” directory
6 – “D:/VideoCall” directory
7 – “C:/Audio” directory
8 – “D:/Audio” directory
FTP_desitanion is a string that contains the complete path with the le name. The string must be start with the character ‘/’,
for example “/lename” or “/directory/lename”.
Example of use:
{
// Uploading a le from Video directory in the 3G microSD card _3G. uploadFile(5, “/FTP_path/FTP_le_name”);
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with CME code (FTP error)
‘-3’ if error getting the le of the size to upload
-36-
v4.9
FTP and FTPS
7.2.4. Downloading les to Waspmote
To download a le to Waspmote’s SD card you can use the function downloadData(FTP_origin, SD_destination, max_
time). FTP_origin and SD_desitanion are strings that contains the complete path with the le name. The strings must be
start with the character ‘/’, for example “/lename” or “/directory/lename”. max_time is the total time in seconds to download the le from the server.
Example of use:
{
// Downloading a le from Waspmote _3G.downloadData(“/FTP_path/FTP_le_name”, “/FTP_path/FTP_le_name”, 180);
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with CME code (FTP error)
‘-3’ if error sending the le from 3G/GPRS module to Waspmote SD
7.2.5. Downloading les to 3G/GPRS module
To download a le to the SD card of the 3G/GPRS module you can use the function downloadFile(FTP_path, SD_
destination_folder, max_time). SD_destination_folder is a number that indicates the destiny folder to the
downloaded le. Allowed values for SD_destination_folder:
0 – current directory
1 – “C:/Picture” directory
2 – “C:/Video” directory
3 – “C:/VideoCall” directory
4 – “D:/Picture” directory
5 – “D:/Video” directory
6 – “D:/VideoCall” directory
7 – “C:/Audio” directory
8 – “D:/Audio” directory
FTP_desitanion is a string that contains the complete path with the le name. The string must be start with the character
‘/’, for example “/lename” or “/directory/lename”. max_time is the total time in seconds to download the le from the server.
Example of use:
{
// Downloading a le from FTP to Video directory _3G. downloadFile(“/FTP_path/FTP_le_name”, 5, 180 );
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with CME code (FTP error)
-37-
v4.9
FTP and FTPS
7.3. FTPS related functions
Note: the 3G/GPRS module doesn’t support FTPS server with certicate authentication. An explicit FTPS server without certicate authentication must be used with these functions.
7.3.1. Log into FTPS server
Before to upload or download les from a FTPS server, you need to log into the FTPS server. The parameters needed to log into the server in order are: server address (can be an IP address or a domain name), port, user name and password.
Example of use:
{
// Setting FTPS parameters _3G.loginFPTS(“ftp_address”, “ftps_port”, “user_name”, “password”);
}
This function returns:
‘1’ on success
‘-2’ if error setting the connection parameters (APN)
‘-3’ if error acquiring the SSL stack
‘-4’ error login into the server
‘-5’ if timeout when logs in
7.3.2. Uploading les from Waspmote
To upload a le from Waspmote’s SD card you can use the function uploadDataSecure(SD_origin, FTPS_destination).
SD_origin and FTPS_destination are strings that contains the complete path with the le name. The strings must be start
with the character ‘/’, for example “/lename” or “/directory/lename”.
Example of use:
{
// Uploading a le from Waspmote _3G.uploadDataSecure(“/SD_path/SD_le_name”, “/FTPS_path/FTPS_le_name”);
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with CME code (FTP error)
‘-3’ if error getting le size from SD
-38-
v4.9
FTP and FTPS
7.3.3. Uploading les from 3G/GPRS module
To upload a le from the SD card of the 3G/GPRS module you can use the function uploadFileSecure(3G_folder, FTPS_
destination_path). 3G_folder is a number that indicates the folder that contains the le to upload. Allowed values for 3G_folder:
0 – current directory
1 – “C:/Picture” directory
2 – “C:/Video” directory
3 – “C:/VideoCall” directory
4 – “D:/Picture” directory
5 – “D:/Video” directory
6 – “D:/VideoCall” directory
7 – “C:/Audio” directory
8 – “D:/Audio” directory
FTPS_desitanion is a string that contains the complete path with the le name. The string must be start with the character ‘/’,
for example “/lename” or “/directory/lename”.
Example of use:
{
// Uploading a le from Video directory in the 3G microSD card _3G. uploadFileSecure(5, “/FTPS_path/FTPS_le_name”);
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with CME code (FTP error)
‘-3’ if error getting the le of the size to upload
7.3.4. Downloading les to Waspmote
To download a le to Waspmote’s SD card you can use the function downloadDataSecure(FTPS_origin, SD_destination).
FTPS_origin and SD_desitanion are strings that contains the complete path with the le name. The strings must be start
with the character ‘/’, for example “/lename” or “/directory/lename”.
Example of use:
{
// Downloading a le from Waspmote _3G.downloadDataSecure(“/FTPS_path/FTPS_le_name”, “/FTPS_path/FTPS_le_name”);
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with CME code (FTP error)
‘-3’ if error sending the le from 3G/GPRS module to Waspmote SD
-39-
v4.9
FTP and FTPS
7.3.5. Downloading les to 3G/GPRS module
To download a le to the SD card of the 3G/GPRS module you can use the function downloadFileSecure(FTPS_path,
SD_destination_folder, max_time). SD_destination_folder is a number that indicates the destiny folder to the
downloaded le. Allowed values for SD_destination_folder:
0 – current directory
1 – “C:/Picture” directory
2 – “C:/Video” directory
3 – “C:/VideoCall” directory
4 – “D:/Picture” directory
5 – “D:/Video” directory
6 – “D:/VideoCall” directory
7 – “C:/Audio” directory
8 – “D:/Audio” directory
FTPS_desitanion is a string that contains the complete path with the le name. The string must be start with the character
‘/’, for example “/lename” or “/directory/lename”. max_time is the total time in seconds to download the le from the server.
Example of use:
{
// Downloading a le from FTPS to Video directory _3G. downloadFileSecure(“/FTPS_path/FTPS_le_name”, 5, 180 );
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with CME code (FTP error)
7.3.6. Log out the FTPS server
Once the uploads or downloads have been completed use the function
Example of use:
{
// Setting FTP parameters _3G.logoutFPTS();
}
This function returns:
‘1’ on success
‘-2’ if error logging out of the server
‘-3’ if error releasing the SSL stack
-40-
v4.9
SMTP and POP3 related functions
8. SMTP and POP3 related functions
Note: to use these features the email servers must work without SSL function.
8.1. Sending email with SMTP
8.1.1. Setting the SMTP server
This function set SMTP server address and server’s port number. SMTP client will initiate TCP session with the specied server to send an e-mail. If SMTP server requires authentication the function must have the user_name and the password. If the process of sending an e-mail is ongoing, the function returns -1 directly.
Example of use:
{
// Sets the SMTP server without authentication : setSMTPserver(“smtp.server.com”, 110,); // Sets the SMTP server with authentication : setSMTPserver(“smtp.server.com”, 110, “user_name”, “password”);
}
This function returns:
‘1’ if success
‘0’ if error setting username and password
‘-1’ if error setting server and port
8.1.2. Setting the sender address and name
This function sets the sender mail address and name.
{
// Sets the sender mail address and the name: setSMTPfrom(“senders_mail.@email.com”, “sender”);
}
This function returns:
‘1’ if success
‘0’ if error
8.1.3. Setting the recipient address and name
The function setSMTPrecipient(kind, index, mail_address, name) sets the recipient mail address and name. For set a normal recipient kind parameter must be 0, 1 for Carbon Copy recipient and 2 for Blind Carbon Copy recipient. The 3G/GPRS module allows ve recipients of each kind (index from 0 to 4).
{
// Sets a normal recipient: setSMTPrecipient(0, 0, recipient_TO@email.com, normal_recicpient); // Sets a Carbon Copy recipient: setSMTPrecipient(1, 2, recipient_CC@email.com, Carcon_Copy_recicpient); // Sets a normal recipient: setSMTPrecipient(2, 4, recipient_BCC@email.com, Blind_Carbon_Copy_recicpient);
}
This function returns:
‘1’ if success
‘0’ if error
-41-
v4.9
SMTP and POP3 related functions
8.1.4. Setting the subject and the body
These functions sets the subject of the email and the body. After an e-mail is sent successfully, the subject and the body will be cleared, if unsuccessfully, they won’t be cleared. Subject and email body are printable ASCII text up to 512 characters each one.
If the process of sending an e-mail is ongoing, these functions will return ‘0’ directly.
{
// Sets the subject: setSMTPsubject(“Subject of the email”); // Sets the body: setSMTPbody(“This is the body of the email”);
}
These functions returns:
‘1’ if success
‘0’ if error
8.1.5. Attaching les
The 3G/GPRS module can attach up to 10 les (0 to 9) to the email. The total size of all attachments can’t exceed 10MB. To attach a le to the email the le must be in the current directory. Please, refer to the File system related functions chapter to know how to go to the correct folder.
If the process of sending an e-mail is ongoing, these functions will return ‘0’ directly.
Example of use:
{
// Attach a picture: setSMTPattach( 1, “picture.jpg”);
}
This function returns:
‘1’ if success
‘0’ if error
8.1.6. Sending the email
This functions sends the email.
Example of use:
{
// Sends the email:
setSMTPsend(); }
This function returns:
‘1’ on success
‘0’ if error setting the APN
‘-2’ error sending the email
‘-3’ if error setting the APN with CME error code available
-42-
v4.9
SMTP and POP3 related functions
8.2. Receiving emails with POP3
8.2.1. Setting the POP3 server parameters
This function sets the parameters for the POP3 server.
Example of use:
{
// Congures the SMTP server: setPOP3server(“pop.server.com”, 110, “username”, ”password”);
}
This function returns:
‘1’ on success
‘0’ if error setting the APN
‘-2’ error sending the email
‘-3’ if error setting the APN with CME error code available
8.2.2. Getting a list of emails
This function get a list with the total number of emails.
Example of use:
{
// Congures the SMTP server: total_email = getPOP3list();
}
This function returns:
the total number of emails
‘-2’ if error logging in the POP3 server
‘-3’ getting the e-mail number and total size
8.2.3. Getting the header of an email
This function gets the header of the email specied in index and stores it in buffer_3G.
Example of use:
{
// Congures the SMTP server: getPOP3header(6);
}
This function returns:
‘1’ on success
‘-1’ if error logging in the POP3 server
‘-2’ if error getting the header of the e-mail
-43-
v4.9
SMTP and POP3 related functions
8.2.4. Getting an email
This function gets the e-mail specied in index and stores it in the location selected with selectStorage(). After retrieving an e-mail successfully, POP3 client will create a directory and save the email’s header and body into le system as le “EmailYYMMDDHHMMSSXYZ.TXT”, and save each attachment as a le under the same directory.
Example of use:
{
// Congures the SMTP server: getPOP3mail(6);
}
This function returns:
‘1’ on success
‘-1’ if error logging in the POP3 server
‘-2’ if error getting the e-mail
8.2.5. Deleting an email
This function deletes the e-mail specied in index. The function only marks an email on the server to delete it, and after POP3 client logs out POP3 server and closes the session normally, the marked email is deleted on the server.
Example of use:
{
// Congures the SMTP server: deletePOP3mail(2);
}
This function returns:
‘1’ on success
‘-1’ if error logging in the POP3 server
‘-2’ if error deleting the e-mail
-44-
v4.9
HTTP and HTTPS
9. HTTP and HTTPS
9.1. HTTP connections
HTTP is a great protocol because it is a standard, simple and light way to send information to web servers.
Libelium has created a little web service in order to allow GPRS, WiFi or 3G modules users to test the HTTP mode. This web service is a little code, written in PHP, which is continuously listening to the HTTP port (port number 80) of our test server “pruebas.libelium.com”. This is a kind of RESTful service. GPRS, WiFi or 3G modules can send HTTP instances to our web service.
HTTP instances should have the following structures so that our web service can understand.
9.1.1. GET method
In GET method the data are sent to the server append to the main URL with the ‘?’ character. The base sentence to perform GET method is shown below:
pruebas.libelium.com/getpost_frame_parser.php?<variable1=value1>&<variable2=value2>&<...>&vie w=html
Where:
getpost_frame_parser.php? : It is the main URL, where the web service is running.
<variable1=value1> : It is a couple with the variable name and value which we want the web service to parse.
view=html : It is an optional argument. It shows a “pretty” response (HTML formatted)
All arguments must be separated by “&”. The variable name and value must be separated by “=”.
Some examples:
pruebas.libelium.com/getpost_frame_parser.php?var1=3.1415
pruebas.libelium.com/getpost_frame_parser.php?var1=3.1415&view=html
pruebas.libelium.com/getpost_frame_parser.php?var1=3.1415&var2=123456&var3=hello&view=html
9.1.2. POST method
Unlike GET method, with POST method the data are sent to the server into an extra data eld. The URL only includes the site name and the PHP direction:
pruebas.libelium.com/getpost_frame_parser.php
The data eld is very similar as the used in GET method:
<variable1=value1>&<variable2=value2>&<...>&view=html
Where:
<variable1=value1> : It is a couple with the variable name and value which we want the web service to parse.
All arguments must be separated by “&”. The variable name and value must be separated by “=”.
Some examples of data eld:
pruebas.libelium.com/getpost_frame_parser.php?variable1=3.141592 pruebas.libelium.com/getpost_frame_parser.php?var1=3.1415&var2=123456&var3=hello
-45-
v4.9
HTTP and HTTPS
9.1.3. Server response
If the web service receives one instance with the appropriate format, some actions will happen:
the web service grabs the string and parses it. So the PHP code creates couples with the variables name and value.
the web service responses to the sender device (to the sender IP) with an HTML-formatted reply.
Figure: Operating with the web service from a PC browser
Figure: Operating with the web service from a Waspmote 3G+GPS
Remember this PHP code is really simple and is oered with the only purpose of testing, without any warranty. The source code is available here:
downloads.libelium.com/waspmote-html-get-post-php-parser-tester.zip
The user may nd it interesting to copy this code and make it run on his own server (physical or virtual). If the user wants to go further, he can complete the code. For example, once the couples are parsed, the user can modify the PHP to save data into a txt le, or insert couples into a database, or include a timestamp...
9.2. Reading an URL
The function readURL(url, port, procedure) is used to launch a HTTP operation like GET or POST,
It accesses to the specied URL and stores the info read in the buffer_3G variable.
Note: Buffer_3G is limited to 512 bytes. If the answer from the HTTP server is greater than 512 bytes data may be lost. The size of the buer can be incremented changing the value of the constant #dene BUFFER_SIZE in Wasp3G.h.
-46-
v4.9
HTTP and HTTPS
Example of use:
{
// Sends a GET procedure to www.url.com _3G.readURL(“www.url.com”, 80, “GET /index HTTP/1.1\r\nHost: www.url.com\r\nUser-Agent: Waspmote\r\nContent-Length: 0\r\n\r\n”);
// Shows the answer from www.url.com USB.println(_3G.buffer_3G);
}
This function returns:
‘1’ on success
‘-1’ if error setting APN, username and password
‘-2’ if error opening a HTTP session
‘-3’ if error receiving data or timeout waiting data
‘-4’ if error changing the baudrate (data received is OK)
‘-5’ if unknown error for HTTP
‘-6’ if HTTP task is busy
‘-7’ if fail to resolve server address
‘-8’ if HTTP timeout
‘-9’ if fail to transfer data
‘-10’ if memory error
‘-11’ if invalid parameter
‘-12’ if network error
‘-15’ if error setting APN, username and password with CME_error code available
‘-16’ if error opening a HTTP session with CME_error code available
Reading an URL using GET and POST methods example:
http://www.libelium.com/development/waspmote/examples/3g-15-getting-url/
9.3. Sending a frame to Meshlium
The function sendHTTPframe( url, port, data, length, method) has been developed to send a frame from Waspmote to Meshlium. Meshlium will parse the frame and will store in the internal database. This function requires the next parameters:
url: IP address from Meshlium
port: HTTP port from Meshlium
data: variable frame.buffer from the frame generated
length: variable frame.length from the frame generated
method: GET or POST
The response from Meshlium will be stored in buffer_3G variable.
Note: Buffer_3G is limited to 512 bytes. If the answer from the HTTP server is greater than 512 bytes data may be lost. The size of the buer can be incrmented changing the value of the constant #dene BUFFER_SIZE in Wasp3G.h.
-47-
v4.9
HTTP and HTTPS
Example of use:
{
// Sends a frame with GET procedure _3G.sendHTTPframe(“www.url.com”, 80, frame.buffer, frame.length, GET);
// Shows the answer from www.url.com USB.println(_3G.buffer_3G);
}
This function returns:
‘1’ on success
‘-1’ if error setting APN, username and password
‘-2’ if error opening a HTTP session
‘-3’ if error receiving data or timeout waiting data
‘-4’ if error changing the baudrate (data received is OK)
‘-5’ if unknown error for HTTP
‘-6’ if HTTP task is busy
‘-7’ if fail to resolve server address
‘-8’ if HTTP timeout
‘-9’ if fail to transfer data
‘-10’ if memory error
‘-11’ if invalid parameter
‘-12’ if network error
‘-15’ if error setting APN, username and password with CME_error code available
‘-16’ if error opening a HTTP session with CME_error code available
‘-17’ if url response its not OK (HTTP code 200)
‘-18’ if content-length eld not found
‘-19’ if data eld not found
Sending a frame to Meshlium using GET and POST methods example:
http://www.libelium.com/development/waspmote/examples/3g-15b-sending-a-frame-to-meshlium/
9.4. HTTPS connections
Hypertext Transfer Protocol Secure (HTTPS) is a combination of the Hypertext Transfer Protocol (HTTP) with SSL/TLS protocol to provide encrypted communication and secure identication of a network web server. HTTPS is the result of simply layering the Hypertext Transfer Protocol (HTTP) on top of the SSL/TLS protocol, thus adding the security capabilities of SSL/TLS to standard HTTP communications. The gure is:
SSL/TLS allows an SSL-enabled server to authenticate itself to an SSL-enabled client, and if necessary, allows the client to authenticate itself to the server. After the authentication and cryptology parameter negotiation, a secure channel is established so that the client and server can exchange information in a secure way.
SSL/TLS Features
Support SSL 3.0 and TLS 1.0
Support SSL client only
Support 512 bits and 1024 bits exportable and non-exportable cipher suits
Support RSA and Ephemeral Die-Hellman key exchange method
Support RSA (with MD5, SHA1 or MD2) and DSS signature algorithm
-48-
v4.9
HTTP and HTTPS
Support Mutual authentication
Support SSL re-handshake
Support DES, 3DES, AES, RC2, and ARCFOUR (compatible with RC4) algorithms.
Support resumed handshake.
Support user interaction in certicate processing.
9.4.1. HTTPS function
The function readURL(url, port, procedure) is used to launch a HTTPS operation like GET or POST.
It accesses to the specied URL and stores the info read in the buffer_3G variable.
Note: Buffer_3G is limited to 512 bytes. If the answer from the HTTPs server is greater than 512 bytes data may be lost. The size of the buer can be incremented changing the value of the constant #dene BUFFER_SIZE in Wasp3G.h.
Example of use:
{
// Sends a GET procedure to www.urls.com _3G.readURLS(“www.urls.com”, 80, “GET /index HTTP/1.1\r\nHost: www.urls.com\r\nUser-Agent: Waspmote\r\nContent-Length: 0\r\n\r\n”);
// Shows the answer from www.urls.com USB.println(_3G.buffer_3G);
}
This function returns:
‘1’ on success
‘-1’ if unknown error
‘-2’ if 3G module is busy
‘-3’ if server closed
‘-4’ if timeout
‘-5’ if transfer failed
‘-6’ if memory error
‘-7’ if invalid parameter
‘-8’ if network error
‘-10’ if error setting APN, username and password
‘-11’ if error acquiring HTTPS protocol stack
‘-12’ if error opening a HTTPS session
‘-13’ if error changing baudrate
‘-14’ if error storing HTTPS request in the output buer
‘-15’ if error sending the HTTPS request to the url
‘-16’ if error with the receive command
‘-17’ if error closing the session (data received is OK)
‘-18’ if error releasing the SSL stack (data received is OK)
‘-19’ if error changing the baudrate (data received is OK)
‘-20’ if error receiving data or timeout waiting data and
‘-25’ if error setting username and password with CME_error code available
-49-
v4.9
GPS
10. GPS
Waspmote 3G board incorporates a GPS receiver capable to work in stand alone mode, MS-based mode and MS-assisted mode.
10.1. Dierences between GPS modes
MS-assisted Server Module
Location server sends aiding data that is valid for the current x
Send aiding data
Module sends code phases Code phases
Server calculates position Calculate position
MS-based Server Module
Location server sends aiding data that is valid for the current x
Send aiding data
Module calculates position Calculate position
Stand alone Server Module
Module demodulates data from GPS satellite
Demodulates GPS satellite data
Module calculates position Calculate position
Figure: Dierences between GPS modes
Standalone – 3G/GPRS module has no connection to the network, and uses only the GPS satellite signals it can currently receive to try to establish a location.
MS Based - 3G/GPRS module is connected to the network, and uses the GPS signals and a location signal from the network. GPS mode will transform to standalone mode automatically after get the ephemeris information from the server .
MS Assisted - 3G/GPRS module is connected to the network, uses GPS signals and a location signal, then relays its ‘x’ to the server.
MS-based and MS-assisted mode depends on URL without certicate. When MS-based mode failing, it will switch standalone mode. MS-assisted mode is single x. Standalone and MS-based mode is consecutive x.
10.2. Technical data from the GPS receiver
Tracking sensitivity: -156 dBm
Acquisition sensitivity: -145 dBm
Accuracy <1.5m (CEP50)
TTFF (Open Sky) Hot start <1s and Cold start <40s
Receiver Type: 12-channel, GPS L1 Frequency (1575.42MHz), C/A Code
Update rate: Default 1 Hz
GPS data format: NMEA-0183
Power consumption: 80mA
GPS antenna: Passive and active antenna
Active antenna voltage: 2.7V
Note: Performance will vary depending on the environment, antenna type and signal conditions and so on.
-50-
v4.9
GPS
10.3. Starting GPS
There are four functions to start the GPS. For startGPScold() and startGPShot() no parameters are required and start the GPS in cold mode and hot mode respectively.
Example of use:
{
// Cold start GPS: _3G.startGPScold(); // Hot start GPS: _3G.startGPShot();
}
These functions returns:
‘1’ on success
‘0’ if error
The function enableAutoGPS() congures the GPS to start automatically when the 3G/GPRS module power on, default GPS is closed. If GPS start automatically, its operation mode is standalone mode. For disable the auto start for the GPS, the function
disableAutoGPS() must be used.
Example of use:
{
// Enable the auto start GPS: _3G.enableAutoGPS(); // Disable the auto start GPS: _3G.disableAutoGPS();
}
These functions returns:
‘1’ on success
‘0’ if error
The function startGPS() are used to start the GPS in the 3 working modes. If the function is called without parameters, the GPS will start in stand-alone mode. To work in MS-based (2) and MS-assisted (3) the user need to give the URL of a A-GPS server and the port. The selected server must work without security certicate.
Example of use:
{
// Start GPS in stand alone mode:
_3G.startGPS();
// Start GPS in MS-based mode: _3G.startGPS(2, “supl.google.com”, “7276”);
// Start GPS in MS-assited mode: _3G.startGPS(3, “supl.google.com”, “7276”);
}
This function returns:
‘1’ on success
‘0’ if error
‘ -2’ if error setting the APN
‘-3’ if error setting GPS server and port,
‘-4’ if error starting the GPS
‘-5’ if AGPS data are not available
-51-
v4.9
GPS
To get the GPS data in stand alone and MS-based mode use the function getGPSinfo(). The GPS data from MS_assisted mode are stored in buffer_3G.
Example of use:
{
// Gets GPS data and shows it: _3G.getGPSinfo(); USB.println(_3G.buffer_3G);
}
These functions returns:
‘1’ on success
‘0’ if error
‘-2’ if info it’s not available
10.4. Stopping the GPS
To stop the GPS use the function stopGPS();
Example of use:
{
// Stops GPS:
_3G.stopGPS(); }
These functions returns:
‘1’ on success
‘0’ if error
10.5. Managing GPS data
The GPS data given by the 3G/GPRS module has 2 formats. The function getGPSinfo() (stand-alone and MS-based) returns the GPS info in specic variables with this units:
Variable Format Example
latitude ±ddmm.mmmmmm +=north and -= south
d: degree; m: minute
4140.831527
longitude ±dddmm.mmmmmm +=east and -= west
d: degree; m: minute
-00053.173495
date ddmmyy
d: day; m: month; y: year
020812
UTC_time hhmmss.s
h: hour; m: minute; s: seconds
083418.0
altitude meters 257.00
speedOG Knots (1knot = 1852m/s) 0
course degrees 0
Figure: Format and example of GPS variables in stand- alone and MS-based modes
-52-
v4.9
GPS
In MS-assited mode the data stored in buffer_3G has this format:
<longitude>, <latitude>, <altitude>, <date>, <time>
Variable Format Example
latitude Unit is in 10^8 degree 4168050885
longitude Unit is in 10^8 degree -88618039
altitude meters 293
date ddmmyyyy
d: day; m: month; y: year
28092012
UTC_time hhmmss.s
h: hour; m: minute; s: seconds
081611.0
Figure: Format and example of GPS variables in MS-assited mode
-53-
v4.9
TCP and UDP connections
11. TCP and UDP connections
Waspmote 3G/GPRS module allows 3 dierent working modes for TCP and UDP connections. The rst one is the single client mode. In this mode, only can connect with a TCP or UDP server. The second one is the multi client mode, with the capacity to work with 10 connections simultaneously. The last one is the server mode. In this mode, the module acts as a TCP server allowing up to 10 clients.
Figure: Dierent working modes
Some functions can return special error codes (CME error code or IP error code). When an error code is available, it will be stored in CME_CMS_code variable. This code can give some extra information about the reason of the error. To know the signication of the code see the appendix CME error codes.
TCP connections maybe need more time than UDP connections. The main reason is the feedback received by the module from the server indicating that the data have been sent successfully or not. With UDP connections there aren’t that feedback.
11.1. Conguration of the 3G/GPRS module for TCP and UDP
Before to open a TCP socket, UDP socket or TCP server, the 3G/GPRS module must be congured with some parameters such as APN, user name (if required), password (if required), number of retries to send and the delay to send the IP packets. These parameters are dened in Wasp3G.h. If the prole doesn’t use the user name and the password, _3G_LOGIN and _3G_PASSW can be commented.
Example of use:
{
// Congures the module for TCP or UDP: _3G.congureTCP_UDP();
}
-54-
v4.9
TCP and UDP connections
Related constants of Wasp3G.h
#dene _3G_APN “myapn” #dene _3G_LOGIN “user_name” #dene _3G_PASSW “password” #dene RETRIES “10” #dene DELAY_SEND “0”
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with CME code is available
‘-3’ if error conguring IP parameters.
11.2. Getting the IP assigned to the module
The function getIP() gets the IP assigned to the module by the network provider. The IP address is stored in buffer_3G.
Example of use:
{
// Gets the IP assigned:
_3G.getIP(); }
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with IP error code available
11.3. Query a IP address from a domain name
This function obtains the IP address from a given domain name. The IP address is stored in buffer_3G.
Example of use:
{
// Query the IP address from a domain name _3G.QueryIPfromDomain(“www.libelium.com”);
}
This function returns:
‘1’ on success
‘0’ if error
-55-
v4.9
TCP and UDP connections
11.4. Query a domain name from a IP address
This function obtains the IP address from a given domain name. The IP address is stored in buffer_3G.
Example of use:
{
// Query the domain from the give IP _3G.QueryIPfromDomain(“80.58.0.33”);
}
This function returns:
‘1’ on success
‘0’ if error
11.5. Working in single client mode
In the single client mode, only one connection can be established with a server. This connection can be TCP or UDP.
The steps to work in this mode are the next:
1. Create a TCP or UDP socket
2. Send and receive data
3. Close the socket
11.5.1. Creating a socket
A socket can be created with the function createSocket(). The parameters needed for create a TCP or UDP socket are dierent. For a TCP socket you need to specify: working mode (TCP_CLIENT), IP address of the server and port of the server. For an UDP socket only need to specify the working mode.
Example of use:
{
// Creating a TCP socket: _3G.createSocket(TCP_CLIENT, “90.12.54.132”, 5566); // Creating a UDP socket:
_3G.createSocket(UDP_CLIENT); }
This function returns:
‘1’ on success
‘-2’ if error opening the network
‘-3’ if error opening the network with CME error code available
‘-4’ if error opening the network with IP error code available
‘-5’ if error opening the TCP connection or starting the TCP server
‘-6’ if error opening the TCP connection or starting the TCP server with IP error code available.
-56-
v4.9
TCP and UDP connections
11.5.2. Sending and receiving data
sendData() is the function for send data to an opened socket. For send data to a TCP socket you only needs the string of data
to send. For send data to a UDP socket, you need the string of data to send, the IP address and the port.
Example of use:
{
// Sending data to a TCP socket: _3G.sendData(“TCP test string”);
// Sending data to a UDP socket: _3G.sendData(“UDP test string”, “90.12.54.132”, 5566);
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with IP error code available
For receive data Waspmote must execute the function manageIncomingData(). This function executes the proper functions and returns a number with the type of data. For IP data this function returns ‘3’. The IP address of the sender is stored in IP_dir and the data in buffer_3G. For more information about the function manageIncomingData(), see the description of the function at this guide.
11.5.3. Closing the socket
To close an opened socket the function closeSocket() must be used. This function doesn’t need parameters.
Example of use:
{
// Closes the socket: _3G.closeSocket();
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with IP error code available
11.6. Working in multi client mode
In the multi client mode, the 3G/GPRS module can establish up to 10 connections with dierent servers. These connections can be TCP or UDP.
The steps to work in this mode are the next:
1. Enable the multi client mode
2. Create a socket
3. Send and receive data
4. Close the socket
-57-
v4.9
TCP and UDP connections
11.6.1. Enable the multi client mode
The function createSocket() with the parameter MULTI_CONNECTION must be used to enable the multi client mode.
Example of use:
{
// Enables the multi client mode:
_3G.createSocket(MULTI_CONNECTION); }
This function returns:
‘1’ on success
‘-2’ if error opening the network
‘-3’ if error opening the network with CME error code available
‘-4’ if error opening the network with IP error code available
11.6.2. Creating sockets
To open a socket in multi client mode the function createMultiSocket(), must be used. To open a TCP socket the next parameters must be specied: number of the link, IP address of the server and port of the server. To open a UDP socket only need the number of the link and the listen port.
Example of use:
{
// Creates a TCP connection in multi client mode: _3G.createMultiSocket(2, “90.12.54.132”, 5566); // Creates a UDP connection in multi client mode: _3G.createMultiSocket(1, 156);
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if not congured in multi client mode
‘-3’ if network is closed
‘-4’ error opening the connection with CME error code available
‘-5’ error opening the connection with IP error code available
11.6.3. Sending and receiving data
To send data to a TCP connection the parameters needed are the number of the connection and the string of data. For send data to a UDP connection the parameters are the number of the connection, the string of data, the IP address of the server and the port of the server.
Example of use:
{
// Sending data to a TCP socket: _3G.sendData(2, “TCP test string”);
// Sending data to a UDP socket: _3G.sendData(1, “UDP test string”, “90.12.54.136”, 5577);
}
-58-
v4.9
TCP and UDP connections
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with IP error code available
For receive data Waspmote must execute the function manageIncomingData(). This function executes the proper functions and returns a number with the type of data. For IP data this function returns ‘3’. The IP address of the sender is stored in IP_dir and the data in buffer_3G. For more information about the function manageIncomingData(), see the description of the function at this guide.
11.6.4. Closing the socket
To close an opened connection the function closeMultiSocket() must be used. This function needs number of the connection to close.
Example of use:
{
// Closes the specify socket: _3G.closeMultiSocket(2);
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with IP error code available
11.7. Working in TCP server mode
The 3G/GPRS module can be used as a TCP server. In this working mode, the 3G/GPRS module can accept up to 10 TCP clients.
11.7.1. Creating the server
A TCP server can be created with the function createSocket(). The parameters needed are the working mode TCP_SERVER and the port of the server.
Example of use:
{
// Creates a TCP server: _3G.createSocket(TCP_SERVER, 80);
}
This function returns:
‘1’ on success
‘-2’ if error opening the network
‘-3’ if error opening the network with CME error code available
‘-4’ if error opening the network with IP error code available
‘-5’ if error opening the TCP connection or starting the TCP server
‘-6’ if error opening the TCP connection or starting the TCP server with IP error code available
-59-
v4.9
TCP and UDP connections
11.7.2. Listing the clients
The function listClients() creates in buffer_3G a list of the clients connected to the TCP server. Each line shows: the number of the client, the IP address of the client and the port of the client.
Example of use:
{
// Lists the clients: _3G.listClients();
}
Example of data stored in buffer_3G:
{
0, 80.58.0.32, 620 1, 194.40.125.10, 800
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with IP error code available
11.7.3. Activate a client
To send and receive data from a client, rst must activated. The number of client starts in 0.
Example of use:
{
// Opens the client number 2: _3G.openClient(2);
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with IP error code available
11.7.4. Sending and receiving data
To send data to an active client use the function sendData().
Example of use:
{
// Sending data to an active client: _3G.sendData(“Test string”);
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with IP error code available
-60-
v4.9
TCP and UDP connections
For receive data Waspmote must execute the function manageIncomingData(). This function executes the proper functions and returns a number with the type of data. For IP data this function returns ‘3’. The IP address of the sender is stored in IP_dir and the data in buffer_3G. For more information about the function manageIncomingData(), see the description of the function at this guide.
11.7.5. Disconnecting a client
The function closeClient() closes an active client.
Example of use:
{
// Opens the client number 2: _3G.closeClient(2);
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with IP error code available
11.7.6. Closing the server
To close the TCP server the function closeSocket() must be used. This function doesn’t need parameters.
Example of use:
{
// Closes the TCP server: _3G.closeSocket();
}
This function returns:
‘1’ on success
‘0’ if error
‘-2’ if error with IP error code available
-61-
v4.9
Miscellaneous functions
12. Miscellaneous functions
12.1. Managing incoming data
It waits for incoming calls, SMSs or TCP/UDP data up to 20 seconds. It executes the function readCall() if a call is received,
readSMS() if an SMS is received and readIPData().
Example of use:
{
// Stores in answer the kind of data received answer = _3G.manageIncomingData(); // Manages incoming data
}
This function returns:
‘1’ for call, Stores the phone number in buffer_3G
‘2’ for SMS. Stores tlfNumber and buffer_3G variables the tlf number and text of the incoming SMS
‘3’ for IP data. Stores the IP address from the sender in IP_dir and the data in buffer_3G
‘0’ for error or not data
Note 1: the phone number has a maximum length of 15 characters, including country code.
Note 2: the SMS text and the TCP/UDP data string has a maximum size of buffer_3G length.
12.2. Getting RSSI level
This function gets the RSSI level from the network and stores it in buffer_3G in dBm.
Example of use:
{
// Getting RSSI level: USB.println(_3G.getRSSI(), DEC);
}
This function returns:
the value in -dBm
‘0’ if error
12.3. Getting cell system information
This function inquires serving cell and neighbours cell system information in GSM.
Example of use:
{
// Gets the cell system information: _3G.getCellsysInfo(); // Shows the information: USB.println(_3G.buffer_3G);
}
-62-
v4.9
Miscellaneous functions
This function returns:
‘1’ on success
‘0’ if error
‘-1’ if timeout
‘-2’ if error restoring the baudrate (data are valid)
Information is stored in buffer_3G with this format:
[SCELL],ARFCN:9,MCC:214,MNC:07,LAC:5002,ID:2432,BSIC:63,RXLev:-95dbm,C1:8,C2:8,TA:0,TXPWR:0 [NCell1],ARFCN:60,MCC:214,MNC:07,LAC:5002,ID:4433,BSIC:37,RXLev:-97dbm,C1:5,C2:5
[SCELL]: indicate serving cell
[NCELLn]: available neighbour cell index
ARFCN: assigned radio channel
MCC: mobile country code
MNC: mobile network code
LAC: localization area code
ID: cell identier
BSIC: base station identication code
RXLev: received signal strength in dBm
TA: timing advance
C1: Coecient for base station selection
C2: Coecient for Cell re-selection
TXPWR: UE TX power in dBm. If no TX, the value is 0.
When the 3G/GPRS module is in dedicated mode (for example in a call is in progress) the parameters MCC, MNC, LAC, ID, C1 and C2 for the neighbour cells are not showed.
12.4. Getting cell channel information
This function inquires serving cell channel information in GSM when a call is in progress.
Example of use:
{
// Gets the cell channel information: _3G.getCellchannel(); // Shows the information: USB.println(_3G.buffer_3G);
}
This function returns:
‘1’ on success
‘0’ if error
Information is stored in buffer_3G with this format:
ARFCN:11,BISC: 4,HSN: 1,MAIO: 1,TN: 2,HF: 1,TSC: 4,TCH: 3
-63-
v4.9
Miscellaneous functions
ARFCN: assigned radio channel
BSIC: base station identication code
HSN: hopping sequence number
MAIO: mobile allocation index oset
TN: timeslot number
HF: hopping ag
TSC: training sequence code
TCH: channel type
12.5. Getting serving cell radio parameters
This function inquires serving cell radio parameter in GSM when a call is in progress.
Example of use:
{
// Gets serving cell radio parameters: _3G.getCellradioparam(); // Shows the information: USB.println(_3G.buffer_3G);
}
This function returns:
‘1’ on success
‘0’ if error
Information is stored in buffer_3G with this format:
ARFCN:9,RXLevFull: -96dbm,RXLevSub: -96dbm,RXQualFull: 4,RXQualSub: 3,PWRC:1,DTX: 1,RLT: 32
ARFCN: assigned radio channel
RXLevFull: received full signal strength in dBm
RXLevSub: received sub signal strength in dBm
RXQualFull: full quality of reception
RXQualSub: sub quality of reception
PWRC: power control
DTX: DTX indicator
RLT: radio link timeout
12.6. Setting preferred service domain
This function sets the preferred service domain. Allowed values are ‘0’ for CS (Circuit Switched), ‘1’ for PS (Packet Switched) and ‘2’ for CS+PS.
Example of use:
{
// Selects CS+PS: _3G.setPreferedServiceDomain(2);
}
This function returns:
‘1’ on success
‘0’ if error
-64-
v4.9
Miscellaneous functions
12.7. Scanning the network band channels
This function scans the network band channels and stores in buffer_3G the data from the channels. You must to specify a start channel and an end channel. The parameter mode selects if the output will be a verbose output (0) or only numeric data (1).
Example of use:
{
// Scans channels from 23 to 33 with verbose output: _3G.scanNetworkchannels(11, 20, 0); // Shows the information: USB.println(_3G.buffer_3G);
}
This function returns:
‘1’ on success
‘0’ if error
Information is stored in buffer_3G with this format when verbose output is selected:
For BCCH-Carrier:
arfcn:<arfcn_value>,bsic:<bsic_value>,dBm:<dBm_value>,mcc: <mcc_value>,mnc:<mnc_value>,lac:<lac_value>,cellId:< cellId>,cellStatus: <cellStasus>,numArfcn:<num_afrcn>,arfcn:<list of arfcns>,numChannels: <num_channel>,array:<list of channels>
For non BCCH-Carrier:
arfch:<arfcn_value>,dBm:<dBm_value>
Information is stored in buffer_3G with this format when numeric output is selected:
For BCCH-Carrier:
<arfcn_value>,<bsic_value>,<dBm_value>,<mcc_value>,<mnc_value>,<lac_value>,<cellId>,<cellStasus>,<num_afrcn>,<list of arfcns>,<num_channel>,<list of channels>
For non BCCH-Carrier:
<arfcn_value>,<dBm_value>
<arfcn_value> : carrier assigned radio channel (BCCH – Broadcast Control Channel)
<bsic_value> : base station identication code
<dBm_value> : the value of dBm
<mcc_value>: mobile country code
<mnc_value> : mobile network code
<lac_value> : localization area code
<cellId> : cell identier
<cellStatus> : cell status, this parameter indicates the following statuses:
- CELL_SUITABLE indicates the C0 is a suitable cell
- CELL_LOW_PRIORITY indicates the cell is low priority based on the system information received
- CELL_FORBIDDEN indicates the cell is forbidden
- CELL_BARRED indicates the cell is barred based on the system information received
- CELL_LOW_LEVEL indicates the cell RXLEV is low
- CELL_OTHER indicates none of the above, e.g. exelusion timer running, no BCCH available , etc.
<num_arfcn> : number of valid channels
-65-
v4.9
Miscellaneous functions
<list of arfcns> : list arfcns BCCH allocation, and the total number is <num_arfcn>
<num_channel> : number of valid channels
<list of channels> : list channels, and the total number is <num_channels>
<arfcn_index> : the index of arfcn, and the minimum value is zero
12.8. Getting UE system information
This function inquires the UE system information. The information returned in ‘buffer_3G’ is dierent from 2G network and 3G network.
Example of use:
{
// Gets UE system information: _3G.getUEsysInfo(); // Shows the information: USB.println(_3G.buffer_3G);
}
This function returns:
‘1’ on success
‘0’ if error
Information is stored in buffer_3G with this format:
For a 2G cell:
<System Mode>,<Operation Mode>,<MCC><MNC> ,<LAC>,<Cell ID>,<Absolute RF Ch Num>, < RxLev >, <Track LO Adjust>,<C1-C2>
For a 3G cell:
<System Mode>,<Operation Mode>,<MCC>,<MNC>,<LAC>,<Cell ID>,<Frequency Band>,<PSC>,<Freq>, <SSC>,<EC/ IO>,<RSCP >,<Qual>,<RxLev>,<TXPWR>
<System Mode> : System mode, values: “NO SERVICE”, “GSM” or “WCDMA”.
<Operation Mode> : UE operation mode, values: “Online”,“Oine”,“Factory Test Mode”,“Reset”, “Low Power Mode”.
<MCC> : Mobile Country Code (rst part of the PLMN code)
<MNC> : Mobile Network Code (second part of the PLMN code)
<LAC> : Location Area Code (hexadecimal digits)
<Cell ID> : Service-cell ID.
<Absolute RF Ch Num> : AFRCN for service-cell.
<Track LO Adjust> : Track LO Adjust
<C1> : Coecient for base station selection
<C2> : Coecient for Cell re-selection
<Frequency Band> : Frequency Band of active set
<PSC> : Primary synchronization code of active set.
<Freq> : Downlink frequency of active set.
<SSC> : Secondary synchronization code of active set
<EC/IO> : Ec/Io value
<RSCP> : Received Signal Code Power
<Qual> : Quality value for base station selection
<RxLev> : RX level value for base station selection
<TXPWR> : UE TX power in dBm. If no TX, the value is 500.
-66-
v4.9
Miscellaneous functions
12.9. Show network system mode
This function shows network system mode.
Example of use:
{
// Shows network mode: USB.println(_3G.showsNetworkMode(), DEC);
}
This function returns:
‘1’ for no service
‘2’ for GSM
‘3’ for GPRS
‘4’ for EGPRS (EDGE)
‘5’ for WCDMA
‘6’ for HSDPA only
‘7’ for HSUPA only
‘8’ for HSPA (HSDPA and HSUPA)
‘0’ if error
‘-1’ if error with CME error code available
12.10. Shows system information in WCDMA
This function shows the mobile phone system information in WCDMA mode. The information are stored in buffer_3G.
Example of use:
{
// Gets WCDMA system information: _3G.WCDMAsysInfo(); // Shows the information: USB.println(_3G.buffer_3G);
}
This function returns:
‘1’ on success
‘0’ if error
Information is stored in buffer_3G with this format:
Active SET,<ActiveSET Cells Num>,<ActiveSET Cell1 PSC>,<ActiveSET Cell1 Freq>,<ActiveSET Cell1 SSC>, <ActiveSET Cell1 Sttd>,<ActiveSET Cell1 TotEcio>,<ActiveSET Cell1 Ecio>,<ActiveSET Cell1 Rscp>,<UTMS_SETS Cell TPC>,<UTMS_SETS Cell SecCpichOvsf>, <ActiveSET Cell1 WinSize> ,... more active cells.
Sync Neighbor SET,<SyncSET Cells Num>,<SyncSET Cell1 PSC>,<SyncSET Cell1 Freq>,<SyncSET Cell1 SSC>,< SyncSET Cell1 Sttd>,< SyncSET Cell1 TotEcio>,< SyncSET Cell1 Ecio>,< SyncSET Cell1 Rscp>,< SyncSET Cell1 WinSize> ,... more sync neighbor cells.
Async Neighbor SET,<AsyncSET Cells Num>,< AsyncSET Cell1 PSC>,< AsyncSET Cell1 Freq>,< AsyncSET Cell1 SSC>,< AsyncSET Cell1 Sttd>,< AsyncSET Cell1 TotEcio>,< AsyncSET Cell1 Ecio>,< AsyncSET Cell1 Rscp>,< AsyncSET Cell1 WinSize> ,... more async neighbor cells.
-67-
v4.9
Miscellaneous functions
<UTMS_SETS Cells Num> : cells number
<UTMS_SETS Cell 1-n PSC> : primary synchronization code of the cell
<UTMS_SETS Cell 1-n Freq> : downlink frequency of the cell
<UTMS_SETS Cell 1-n SSC> : secondary synchronization code
<UTMS_SETS Cell 1-n Sttd> : if the CPICH of this cell uses STTD
<UTMS_SETS Cell 1-n TotEcio> : the total Ec/Io in the best paths found in a sweep
<UTMS_SETS Cell 1-n 1 Ecio> : Ec/Io
<UTMS_SETS Cell 1-n Rscp> : CPICH RSCP
<UTMS_SETS Cell 1-n TPC> : Forward power control combination
<UTMS_SETS Cell 1-n SecCpichOvsf>: OVSF code of the secondary CPICH
<UTMS_SETS Cell 1-n WinSize>: search window size for this cell
UTMS_SETS contains:
ActiveSET : active set
SyncSET: neighbour (monitored) set for neighbours whose timing is known
AsyncSET: neighbour (monitored) set for neighbours whose timing is unknown
12.11. Setting network system mode preference
This function sets network system mode preference. The values for the input parameter are: ‘0’ for automatic, ‘13’ for GSM only and ‘14’ for WCDMA only.
Example of use:
{
// Sets network system mode for WCDMA only: _3G.setNetworkMode(14);
}
This function returns:
‘1’ on success
‘0’ if error
12.12. Setting the preferences for order of acquisitions
This function sets the preferences for order acquisitions mode. The input parameter species the order: ‘0’ for automatic, ‘1’ GSM,WCDMA and ‘2’ for WCDMA,GSM.
Example of use:
{
// Sets the order to work rst with WCDMA: _3G.modeAcquisitionsOrder(2);
}
This function returns:
‘1’ on success
‘0’ if error
-68-
v4.9
Miscellaneous functions
12.13. Choosing the storage location
This function selects the location (local storage or SD card storage) of store the data captured by the 3G/GPRS module as pictures, video or emails. The values for input parameter can be: ‘0’ for local storage and ‘1’ for SD card storage.
Example of use:
{
// Selects microSD card to store data: _3G.selectStorage(1);
}
This function returns:
‘1’ on success
‘0’ or ‘-2’ if error
12.14. Changing the baudrate
This function changes the baudrate between Waspmote and 3G/GPRS module. This function also changes the UART’s baudrate in Waspmote. The allowed baudrates are: 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200. Higher values don’t work properly in Waspmote.
Example of use:
{
// Sets baudrate to 38400 bauds: _3G.changeBaudrate(38400);
}
This function returns:
‘1’ on success
‘0’ or ‘-2’ if error
12.15. Sending AT commands to the 3G/GPRS module
This function allows to the user to send AT commands to the 3G/GPRS module and read the answer from it. The command must a string without the “AT”. The answer is stored in buffer_3G with this format.
Example of use:
{
// Sends “AT+CREG”: _3G.sendATCommand(“+CREG?”); // Shows the answer: USB.println(_3G.buffer_3G);
}
This function returns:
‘1’ on success
‘0’ if error
-69-
v4.9
Miscellaneous functions
12.16. Choosing audio output
This functions selects the output for the audio. Allowed values are ‘0’ for speaker and ‘1’ for loudspeaker.
Example of use:
{
// Selects the loudspeaker for audio: _3G.selectAudioOutput(1);
}
This function returns:
‘1’ on success
‘0’ if error
12.17. Setting the gain level of the microphone
This function sets the gain level of the microphone. The input values are:’ 0’ for mute and ‘1’ to ‘16’ for gain level. Mute only can be used into a call.
Example of use:
{
// Sets max gain for the microphne amplier: _3G.micGain(16);
}
This function returns:
‘1’ on success
‘0’ if error
12.18. Setting the loudspeaker volume
This function sets the level of the loudspeaker. The input values are:’ 0’ for mute and ‘1’ to ‘5’ for volume level.
Example of use:
{
// Sets mmute for the loudspeaker: _3G.loudspeakerLevel(0);
}
This function returns:
‘1’ on success
‘0’ if error
-70-
v4.9
Miscellaneous functions
12.19. Getting module information
The function whoamI() get the model of the module and saves it in buffer_GPRS. The function rmware_version() get the rmware of the module and saves it in buffer_GPRS.
These functions return ‘1’ on success, ‘0’ if error.
Example of use:
{
USB.print(F(“WhoamI: “)); GPRS_Pro.whoamI(); USB.println(GPRS_Pro.buffer_GPRS); USB.print(F(“Firmware version: “)); GPRS_Pro.rmware_version(); USB.println(GPRS_Pro.buffer_GPRS);
}
-71-
v4.9
Geolocation tracker application example
13. Geolocation tracker application example
The 3G+GPS module allows the developer to send the GPS location and sensor data to the cloud, via 3G or GPRS. This chapter shows how to track a Waspmote with the 3G+GPS module and see in the web with Google Maps API. The example for Waspmote and the PHP script for the server are shown as help or inspiration for the developer.
Before starting to use Waspmote, you must install the PHP script (shown at the end of the chapter). To use the PHP script you need an Apache server with PHP active. You can run the script in a PC installing Apache with PHP. You can do this easily with the installer from these websites (or the package manager for Linux):
For Windows use WAMP: http://www.wampserver.com/
For Linux use LAMP: Use your package manager in Linux
For Mac use MAMP: http://www.mamp.info/
In these websites, you have manuals to help you to install the server and activate PHP. Extract the PHP script on your computer. You must change the Google Maps API v3 key in the PHP script:
http://maps.googleapis.com/maps/api/js?key=your_key&sensor=false”
To show the map with the marker you need to access to the next URL:
http://your_IP_or_domain/demo_sim908.php
The IP address or server domain must be the same used in the example code of Waspmote (in case you are running the demo on your computer, replace “your_IP_or_domain” by “localhost”)
Once the PHP script has been installed and Waspmote has the example code (3G+GPS 31: demo GPS tracker) uploaded, Waspmote can be switched on. Remember, you must congure your APN, login and password. If you don’t do this, the 3G+GPS module cannot connect to the 3G or GPRS network. Also, you must set the URL with the IP address of your computer (external IP, not the LAN IP address) or your server’s domain.
When the GPS xes the GPS satellites, the 3G+GPS module will connect to the network and send the GPS data through the Internet to the PHP script in your computer. When a frame is received, a marker will be shown in the map.
Figure: Geolocation tracker demo - Map Figure: Geolocation tracker demo - Satellite
-72-
v4.9
Geolocation tracker application example
<?php if (!empty($_GET[‘latitude’]) && !empty($_GET[‘longitude’]) && !empty($_GET[‘time’]) && !empty($_GET[‘satellites’]) && !empty($_GET[‘speedOTG’]) && !empty($_GET[‘course’])) { function getParameter($par, $default = null){ if (isset($_GET[$par]) && strlen($_GET[$par])) return $_GET[$par]; elseif (isset($_POST[$par]) && strlen($_POST[$par])) return $_POST[$par]; else return $default;
}
$le = ‘gps.txt’; $lat = getParameter(“latitude”); $lon = getParameter(“longitude”); $time = getParameter(“time”); $sat = getParameter(“satellites”); $speed = getParameter(“speedOTG”); $course = getParameter(“course”); $person = $lat.”,”.$lon.”,”.$time.”,”.$sat.”,”.$speed.”,”.$course.”\n”;
echo “ DATA:\n Latitude: “.$lat.”\n Longitude: “.$lon.”\n Time: “.$time.”\n Satellites: “.$sat.”\n Speed OTG: “.$speed.”\n Course: “.$course; if (!le_put_contents($le, $person, FILE_APPEND | LOCK_EX)) echo “\n\t Error saving Data\n”; else echo “\n\t Data Save\n”;
}
else { ?> <!DOCTYPE html> <html>
<head> <!-- Load Jquery --> <script language=”JavaScript” type=”text/javascript” src=”jquery-1.10.1.min.js”></ script> <!-- Load Google Maps Api --> <!-- IMPORTANT: change the API v3 key --> <script src=”http://maps.googleapis.com/maps/api/js?key=your_key&sensor=false”></ script> <!-- Initialize Map and markers --> <script type=”text/javascript”> var myCenter=new google.maps.LatLng(41.669578,-0.907495); var marker; var map; var mapProp; function initialize()
{
mapProp = { center:myCenter, zoom:15, mapTypeId:google.maps.MapTypeId.ROADMAP
};
setInterval(‘mark()’,5000);
}
function mark()
{
map=new google.maps.Map(document.getElementById(“googleMap”),mapProp); var le = “gps.txt”; $.get(le, function(txt) { var lines = txt.split(“\n”); for (var i=0;i<lines.length;i++){
-73-
v4.9
Geolocation tracker application example
console.log(lines[i]); var words=lines[i].split(“,”); if ((words[0]!=””)&&(words[1]!=””))
{
marker=new google.maps.Marker({ position:new google.maps.LatLng(words[0],words[1]),
}); marker.setMap(map);
map.setCenter(new google.maps.LatLng(words[0],words[1])); document.getElementById(‘sat’).innerHTML=words[3]; document.getElementById(‘speed’).innerHTML=words[4]; document.getElementById(‘course’).innerHTML=words[5];
} }
marker.setAnimation(google.maps.Animation.BOUNCE);
}); }
google.maps.event.addDomListener(window, ‘load’, initialize); </script> </head> <body> <?php echo ‘ <!-- Draw information table and Google Maps div --> <div> <center><br /> <b> SIM908 GPS position DEMO </b><br /><br /> <div id=”superior” style=”width:800px;border:1px solid”> <table style=”width:100%”> <tr> <td>Time</td> <td>Satellites</td> <td>Speed OTG</td> <td>Course</td> </tr> <tr> <td id=”time”>’. date(“Y M d - H:m”) .’</td> <td id=”sat”></td> <td id=”speed”></td> <td id=”course”></td> </tr> </table> </div> <br /><br /> <div id=”googleMap” style=”width:800px;height:700px;”></div> </center> </div>’; ?> </body> </html> <?php } ?>
Geolocation tracker example:
http://www.libelium.com/development/waspmote/examples/3g-31-demo-gps-tracker
-74-
v4.9
API changelog
14. API changelog
Keep track of the software changes on this link:
www.libelium.com/development/waspmote/documentation/changelog/#3G
-75-
v4.9
Documentation changelog
15. Documentation changelog
From v4.8 to v4.9
Reference to the new GPRS+GPS module version (chipset SIM908)
From v4.7 to v4.8:
Link to the new online API changelog
From v4.6 to v4.7:
Added new chapter “Geolocation tracker application example”
Added the new GPRS+GPS module to the comparative table
API changelog updated to API v011
Added new section “Setting operator parameters” in chapter “Initialization”
From v4.5 to v4.6:
New section “Sending a frame” added in chapter “HTTP and HTTPS”.
API changelog updated
From v4.4 to v4.5:
API changelog updated
From v4.3 to v4.4:
Added new section “HTTP connections” added in chapter “HTTP and HTTPS”.
Added new section “GET method” added in chapter “HTTP and HTTPS”.
Added new section “POST method” added in chapter “HTTP and HTTPS”.
Added new section “Server response” added in chapter “HTTP and HTTPS”.
Section “HTTP” changes to “Reading an URL”
From v4.2 to v4.3:
API changelog updated
From v4.1 to v4.2:
New section “Getting module information” added in chapter “Miscelaneous functions”.
Added return codes in section “3G power modes”.
Section “Checking the GSM connection” has been updated.
OTA feature added in section “Hardware”.
Added new section “Creating your own FTP server” in chapter “FTP and FTPS”.
API changelog updated.
From v4.0 to v4.1:
Added notes about carriers in US in sections “Hardware” and “Checking the GSM connection”.
-76-
Apendix A. CME error codes
v4.9
Apendix A. CME error codes
CME error code Description CME error code Description
0 phone failure 112 Location area not allowed
1 no connection to phone 113 Roaming not allowed in this location area
2 phone adaptor link reserved 132 service option not supported
3 operation not allowed 133 requested service option not subscribed
4 operation not supported 134 service option temporarily out of order
5 PH-SIM PIN required 148 unspecied GPRS error
6 PH-FSIM PIN required 149 PDP authentication failure
7 PH-FSIM PUK required 150 invalid mobile class
10 SIM not inserted 257 network rejected request
11 SIM PIN required 258 retry operation
12 SIM PUK required 259 invalid deected to number
13 SIM failure 260 deected to own number
14 SIM busy 261 unknown subscriber
15 SIM wrong 262 service not available
16 incorrect password 263 unknown class specied
17 SIM PIN2 required 264 unknown network message
18 SIM PUK2 required 273 minimum TFTS per PDP address violated
20 memory full 274 TFT precedence index not unique
21 invalid index 275 invalid parameter combination
22 not found 201 Unknown error for FTP
23 memory failure 202 FTP task is busy
24 text string too long 203 Failed to resolve server address
25 invalid characters in text string 204 FTP timeout
26 dial string too long 205 Failed to read le
27 invalid characters in dial string 206 Failed to write le
30 no network service 207 It’s not allowed in current state
31 network timeout 208 Failed to login
32 network not allowed - emergency calls only 209 Failed to logout
40 network personalization PIN required 210 Failed to transfer data
41 network personalization PUK required 211 FTP command rejected by server
42 network subset personalization PIN required 212 Memory error
43 network subset personalization PUK required 213 Invalid parameter
44 service provider personalization PIN required 214 Network error
45 service provider personalization PUK required 220 Unknown error fot HTTP
46 corporate personalization PIN required 221 HTTP task is busy
47 corporate personalization PUK required 222 Failed to resolve server address
100 Unknown 223 HTTP timeout
103 Illegal MESSAGE 224 Failed to transfer data
106 Illegal ME 225 Memory error
107 GPRS services not allowed 226 Invalid parameter
111 PLMN not allowed 227 Network error
-77-
Apendix B. CMS error codes
v4.9
Apendix B. CMS error codes
CME error code Description CME error code Description
300 ME failure 316 SIM PUK required
301 SMS service of ME reserved 317 SIM PIN2 required
302 Operation not allowed 318 SIM PUK2 required
303 Operation not supported 320 Memory failure
304 Invalid PDU mode parameter 321 Invalid memory index
305 Invalid text mode parameter 322 Memory full
310 SIM not inserted 330 SMSC address unknown
311 SIM PIN required 331 no network service
312 PH-SIM PIN required 332 Network timeout
313 SIM failure 340 NO +CNMA ACK EXPECTED
314 SIM busy 342 SMS size more than expected
315 SIM wrong 500 unknown error
Loading...