Skip to content

gsm

Jump to bottom
Boris Lovosevic edited this page Jul 30, 2019 · 8 revisions

network Module

Class gsm

This module includes full support for using various GSM/GPRS modules connected via UART for Internet access as well as for sending/receiving SMS messages.

2G, 3G or 4G modules can be used, tested with Simcom and Telit modules, but any module should work.

Connecting the GSM module

K210 pin GSM module Notes
TX Rx GSM module Rx pin (input)
RX Tx GSM module Tx pin (output)
GND GND Power supply ground
... Vcc GSM module power supply, usualy 3.4~4.2 V (LiPo battery)
Do not connect to the K210 board's 5V, unless the GSM module has its own woltage regulator.

No flow control is used at the moment.

GSM modules usualy have IO interface pins working in 2.8 or 1.8 V range.
When connecting to K210 3.3V pin, level shifters must be used

If the GSM module has 2.8V interface pins (like SIM800), the module can be connected without level shifters:

  • GSM module output (Tx) can be connected directly to K210 input (Rx).
  • GSM module input (Rx) can be connected to the K210 output (Tx) via schottky diode in a way that diode cathode is facing K210 pin. GSM module's Rx pin must have pull-up resistor (~10K) to 2.8V (SIM800 has this resistor integrated).

Some GSM modules have ON/OFF pin. If used, it must be handled outside of this module (use machine.Pin).

All GSM operations are controlled by the FreeRTOS task.

After initialization, the GSM can be in two different states:

  • online - connected to the Internet, all network functions works the same way as with Internet connection via WiFi.
  • offline - disconnected from the Internet, SMS functions can be executed as well as any of the GSM AT commands

To use this class it must first be imported.

from network import gsm

or

import network
gsm = network.gsm

Methods


gsm.start( args )

Start the GSM task, initialize GSM, optionaly start PPPoS and connect to the Internet.

All arguments are KW arguments.

Pins have to be given as pin numbers, not the machine.Pin objects

Argument Description
tx UART Tx output on K210, connected to the GSM Rx input
rx UART Rx input on K210, connected to the GSM Tx output
apn Your Internet provider's APN
rts optional, not used
cts optional, not used
user optional, user name if required by the provider
Default: ""
password optional, password if required by the provider
Default ""
connect optional, if set to True connects to the Internet after GSM initialization
Default: False
wait optional, wait for operation to finish if set to True.
If False, return immediately, connection status can be checked with gsm.status()
Default: False
roaming optional, enable connection in roaming if set to True
Default: False 
>>> gsm.debug(True)
>>> gsm.start(tx=20, rx=21, apn="internet.ht.hr", wait=True)
M (3377046) [GSM_PPPOS]: Initialize UART
M (3380698) [GSM_PPPOS]: UART #0, initialize uart hardware
D (3386699) [PINS]: Set pin 21 to function 64
D (3391116) [PINS]: Set pin 20 to function 65
M (3495395) [GSM_PPPOS]: UART #0 initialized: tx=20, rx=21, bdr=115205
M (3521411) [GSM_PPPOS]: GSM TASK STARTED
M (3624475) [ATCMD]: Check and set device baudrate
M (3642494) [ATCMD]: Device communicating at 115200 bd
M (3647359) [GSM_PPPOS]: Set APN
M (3651098) [GSM_PPPOS]: Wait for no data from GSM module
M (3756561) [GSM_PPPOS]: GSM initialization start
M (4270881) [ATCMD]: AT COMMAND: [AT\r\n] Expecting: [\r\nOK\r\n]
M (4278886) [ATCMD]: AT RESPONSE: match condition 1 at position 0 (2 ms, 0 byte(s), buf_start=0)
M (4296893) [ATCMD]: AT COMMAND: [ATZ\r\nATE0\r\n] Expecting: [\r\nOK\r\n]
M (4307900) [ATCMD]: AT RESPONSE: match condition 1 at position 0 (3 ms, 0 byte(s), buf_start=0)
M (4325906) [ATCMD]: AT COMMAND: [ATE0\r\n] Expecting: [\r\nOK\r\n]
M (4335913) [ATCMD]: AT RESPONSE: match condition 1 at position 5 (3 ms, 0 byte(s), buf_start=0)
M (4353919) [ATCMD]: AT COMMAND: [AT+CFUN=1\r\n] Expecting: [\r\nOK\r\n]
M (4362924) [ATCMD]: AT RESPONSE: match condition 1 at position 0 (1 ms, 0 byte(s), buf_start=0)
M (5581680) [ATCMD]: AT COMMAND: [AT+CMGF=1\r\n] Expecting: [\r\nOK\r\n]
M (5592685) [ATCMD]: AT RESPONSE: match condition 1 at position 0 (4 ms, 0 byte(s), buf_start=0)
M (5610693) [ATCMD]: AT COMMAND: [AT+CPIN?\r\n] Expecting: [CPIN: READY]
M (8683371) [ATCMD]: AT RESPONSE: match condition 1 at position 9 (3066 ms, 0 byte(s), buf_start=0)
M (8701379) [ATCMD]: AT COMMAND: [AT+CREG?\r\n] Expecting: [CREG: 0,1]
M (8712386) [ATCMD]: AT RESPONSE: match condition 1 at position 3 (4 ms, 0 byte(s), buf_start=0)
M (10731635) [ATCMD]: AT COMMAND: [AT+CNMI=0,0,0,0,0\r\n] Expecting: [\r\nOK\r\n]
M (10743641) [ATCMD]: AT RESPONSE: match condition 1 at position 0 (3 ms, 0 byte(s), buf_start=0)
M (10761650) [ATCMD]: AT COMMAND: [AT+CGDCONT=1,"IP","internet.ht.hr"\r\n] Expecting: [\r\nOK\r\n]
M (10780660) [ATCMD]: AT RESPONSE: match condition 1 at position 0 (7 ms, 0 byte(s), buf_start=0)
M (10789276) [GSM_PPPOS]: PPPoS control block created
M (10794816) [GSM_PPPOS]: GSM initialized and ready.
M (10800282) [GSM_PPPOS]: PPPoS IDLE mode
M (10804796) [GSM_PPPOS]: PPPoS IDLE mode

gsm.stop([wait])

Disconnect from the Internet if connected, stop the GSM task and free the memory used.
If the optional argument wait is True, waits until the gsm task is stopped..

gsm.status()

Return the current GSM status as tuple of numeric and string values.
Possible return values:

  • (98, Not started) GSM task not started or initializing
  • (0, Disconnected) PPPoS started, disconnected from Internet
  • (1, Connected) PPPoS started, connected to Internet, network functions can be used
  • (2, Connecting) PPPoS started, connecting to Internet, network functions cannot yet be used
  • (89, Idle) GSM initialized, PPPoS not started, SMS and AT commands can be used

gsm.ifconfig()

Get gsm connection properties.
Returns the current network configuration as 3-item tuple (ip_address, net_mask, gateway_ip).

gsm.ifconfig()
('10.198.36.232', '255.255.255.255', '10.64.64.64')
>>>

gsm.connect([args])

If in Idle state, start PPPoS and connect to the Internet.

Optional arguments:

Argument Description
connstr Use the specified connection string instead of the dafault one "ATDT*99***1#\r\n"
For exampe, "AT+CGDATA=\"PPP\",1\r\n" can be used, or other specific to the GSM module used.
fullinit If True, perform a full GSM initialization before connect
Default; False
wait If True wait for the connection to be established
Default: False

If succesfully connected, NTP service will be started and system time will be automatically updated.
If ntp callback is set, it will be executed on NTP synchronization.

>>> gsm.connect()
True
>>> 
M (152905929) [GSM_PPPOS]: Connect requested.
M (152910015) [GSM_PPPOS]: GSM initialization start
M (153425260) [ATCMD]: AT COMMAND: [AT+CGDCONT=1,"IP","internet.ht.hr"\r\n] Expecting: [\r\nOK\r\n]
M (153444270) [ATCMD]: AT RESPONSE: match condition 1 at position 0 (7 ms, 0 byte(s), buf_start=0)
M (153462276) [ATCMD]: AT COMMAND: [ATDT*99***1#\r\n] Expecting: [CONNECT]
M (153473282) [ATCMD]: AT RESPONSE: match condition 1 at position 2 (3 ms, 0 byte(s), buf_start=0)
M (154481907) [GSM_PPPOS]: GSM initialized, waiting for connection...
M (154488074) [GSM_PPPOS]: Using uart semaphore (1)
M (154493457) [GSM_PPPOS]: Configure PPPoS
M (154801111) [GSM_PPPOS]: PPPoS loop
M (157819493) [GSM_PPPOS]: status_cb: Code 0
M (157823491) [GSM_PPPOS]: status_cb: Error=None, Connected
M (157829570) [GSM_PPPOS]: status_cb: Connected
M (157834602) [GSM_PPPOS]:    ipaddr    = 10.185.104.227
M (157840418) [GSM_PPPOS]:    gateway   = 10.64.64.64
M (157845973) [GSM_PPPOS]:    netmask   = 255.255.255.255
M (157851885) [GSM_PPPOS]: NTP service started
M (316104124) [NTP]: Time synchronized from NTP (1564495226)

gsm.disconnect([wait])

If in Connected state, disconnect from Internet and stop PPPoS.
If the optional argument wait is True, waits for disconnection.

gsm.debug(True|False)

Enable or disable low level gsm module communication logging.

gsm.sendSMS(gsm_num, msg)

Send SMS message msg to the gsm number gsm_num.
The number has to be in the international format +<counry_code><number>

Returns True if message successfully sent, False if not.

gsm.checkSMS(sort=gsm.SORT_NONE, status=gsm.SMS_ALL)

Chech the number of received messages.

Returns tuple of message indexes or None if no messages are found.
If the optional argument sort is provided, returned indexes can be sorted by message time in ascending (gsm.SORT_ASC) or descending (gsm.SORT_DESC) order.
if the optional argument status is provided, the returned indexes can be filtered by message status (gsm.SMS_ALL, gsm.SMS_READ, gsm.SMS_UNREAD).

gsm.readSMS(idx [,delete=False])

Read and return the message at index idx or None if no message is found at that index.
idx should be one of the indexes obtained by gsm.smsCheck().

If the optional argument delete is True delete the message after reading.

The message is returned as 7-item tuple:

Position Content Note
0 idx integer, message index
1 status string: "REC UNREAD" or "REC READ"
2 from string, sender's GSM number in international format
3 time string, message time as string in GSM format
4 timeval integer, message time as unix time
5 tz integer, message time zone
6 msg string, message text

gsm.deleteSMS(idx)

Delete the message at index idx. Returns True on success or False if no message is found at that index.

>>> gsm.checkSMS()
(1, 2, 3, 4, 5, 6, 7, 9)
>>> gsm.checkSMS(sort=gsm.SORT_DESC)
(9, 7, 6, 5, 4, 3, 2, 1)
>>> gsm.readSMS(9)
(9, 'REC READ', '+38599xxxxxxx', '19/07/30,21:12:56+08', 1564521176, 2, 'Message to K210 MicroPython with GSM')

gsm.sms_cb(function [,interval])

Register the callback function which will be executed on new message arrival.

Message check interval can be set by optional interval argument to 5 ~ 86400 seconds.
Default check interval is 60 seconds.

The argument returned to the callback function is tuple of unread message indexes sorted in descending order.

Use gsm.sms_cb(None) to unregister callback function and stop checking for new messages.

def smscb(indexes):
    if indexes:
        #read only the last message
        msg = gsm.readSMS(indexes[len(indexes)-1], True)
        if msg:
            print("New message from {}, sent at {}".format(msg[2], msg[3]))
            print(msg[6])

>>> gsm.sms_cb(smscb, 30)
New message from +38599xxxxxxx, sent at 19/07/30,22:01:25+08
Hi K210 MicroPython with GSM

gsm.ntp_cb(function])

Register the callback function which will be executed when time is synchronized from NTP server.

import network, time

def ntp_cb(res):
    # res is the Unix time (seconds from epoch)
    print("Time synchronized: {}".format(res))
    print(time.strftime("%c"))

>>> gsm = network.gsm
>>> gsm.start(tx=20, rx=21, apn="internet.ht.hr", wait=True)
True
>>> gsm.status()
(89, 'Idle')
>>> gsm.ntp_cb(ntp_cb)
True
>>> gsm.connect(wait=True)
True
>>> Time synchronized: 1564499514
Tue Jul 30 15:11:54 2019

>>> gsm.status()
(1, 'Connected')
>>>

wifi.atcmd(cmd, timeout=500, response=('OK', 'ERROR'), delay=5, incresp=True)

Execute any AT Command.
This method provides flexible and feature rich way of executing AT Commands and parsing the result.
Single or multiple AT commands can be executed and single or multiple responses can be processed.

Single AT command processing

Argument Description
cmd string starting with AT
response string containing expected command response
or
tuple of strings containing the condition on which the waiting for the response will be terminated as successful
timeout timeout in ms for waiting for the response.
Default 500
incresp If set to False the terminating condition will not be included in the result.
Default: True
delay not used

Multiple AT command processing

Argument Description
cmd tuple containing the AT commands to be executed.
Each tuple item must itself be a tuple:
(command_data, is_data, timeout, response, repeat, incresp)
command_data - at command or data to be send
is_command set to True if command_data is data to be send, not the command
response not used, response from command tuple is used
timeout not used, timeout from command tuple is used
incresp not_used, incresp from command tuple is used
delay delay between commands in ms

Content

Building

Downloads

Modules

Running two MicroPython instances

Frozen Modules

Documents and links

If you find this project useful, you can contribute by making a donation
Donate

Clone this wiki locally