Cellular
Cellular¶
This module implements a generic Cellular interface. To function correctly it needs a cellular driver to be loaded, so that the module can use the driver to access the underlying hardware.
The link between the cellular module and the cellular driver is established without the programmer intervention by the driver itself.
This module defines the following constants:
BG95_M3
= 0; Quectel BG95-M3 Cellular module as modem type.BG96
= 1; Quectel BG96 Cellular module as modem type.
Exceptions¶
exception CellularException
¶
Generic cellular exception.
exception CellularModemInitError
¶
The modem initialization failed.
exception CellularModemConfigurationError,
¶
The modem not configured or configuration is not valid.
exception CellularInvalidStateError
¶
The modem or GNSS is in an invalid state.
exception CellularBadAPN
¶
The configured APN for PPP connection is not valid.
exception CellularCommandError
¶
The command sent to the modem or GNSS failed.
exception CantRegisterInterfaceError
¶
The cellular network interface cannot be registered.
exception ConnectionTimeoutError
¶
The cellular network connection start timed out.
exception GNSSException
¶
The exception related to GNSS submodule.
exception GNSSInitError
¶
The GNSS (Global Navigation Satellite System) submodule initialization failed.
exception GNSSTimeoutError
¶
The GNSS fix operation timed out.
Functions¶
function configure
¶
configure(apn="zerynth-apn", apn_user="", apn_password="", dhcp=True, ip="", mask="", gateway="", dns="8.8.8.8", timeout=10000, modem_type=BG95_M3, name="cellular", force_dns=False)
apn
: is the APN for the network connection. It depends from the SIM card provider. The default is the APN for a Zerynth SIM.apn_user
: the username for the network connection authentication. Usually it is empty. Default value empty string.-
apn_password
: the password for the network connection authentication. Usually it is empty. Default value empty string. -
dhcp
: enable DHCP for IP parameters. Default value is True. Ifdhcp
is Trueip
,mask
,gateway
,dns
arguments are ignored. Note For thedns
see also theforce_dns
argument. Whendhcp
is False, the arguments for IP parameters are: -
ip
: is the static IP address. Default value is empty string. mask
: the net mask expressed as A.B.C.D dotted address. Default value is empty string.gateway
: the gateway IP address to be used as default router. Default value is empty string.-
dns
: the Domain Name Server to be used for name resolution. Whendhcp
is True this parameter is ignored, unlessforce_dns
is True. Default value is "8.8.8.8", the Google DNS. -
force_dns
: forces a custom DNS address when DHCP is on. When theforce_dns
is True the DNS address provided by the DHCP server is ignored. Default value is False. timeout
: Connection timeout in milliseconds.CellularException
is raised if connection do not succeed during this time. Default value is 10000 ms.modem_type
: the Cellular hardware module type. Default value is BG95_M3.name
: the interface name to be used in a multi interface scenario. Default value is "cellular".
function init
¶
init()
function deinit
¶
deinit()
function reset
¶
reset()
function start
¶
start()
configure()
function. If the cellular module is also initialized, should it was not done yet. function stop
¶
stop()
function resolve
¶
resolve(host, name="cellular")
host
to its IP address by using the configured DNS server and returning a string with the result. The name
interface is used in a multi interface scenario. Default name
value is "cellular". function info
¶
info(name="cellular")
name
d interface. The tuple is composed by the following elements: Bool
: DHCP enabled (True) or disabled (False)String
: IP addressString
: netmaskString
: gatewayString
: DNSString
: MAC address
function interface
¶
interface(name="cellular")
name
d interface. Default name
value is "cellular". function atmode
¶
atmode()
function pppmode
¶
pppmode()
function imei
¶
imei()
String
. function imsi
¶
imsi()
String
. function iccid
¶
iccid()
String
. function rssi
¶
rssi()
function cellinfo
¶
cellinfo()
String
: The state of the modem connection. Can be: SEARCH, LIMSRV, NOCONN, CONNECT.String
: Access technology. Can be: No Service, GSM, GPRS, EDGE, eMTC, NB-IoT.String
: Operator code. 3 chars for MCC, 3 chars for MNC.String
: Selected bandInteger
: Channel IDInteger
: Local Area CodeInteger
: Cell IDInteger
: Base station ID codeInteger
: Operator MCCInteger
: Operator MNCString
: Operator name
The values meaning for the element 0 of the tuple, the connection state, are:
SEARCH
: the modem is not registered to any cell and is in searching modeLIMSRV
: the modem has registered to the cell but cannot exchange data yet.NOCONN
: the modem is in idle state. UE (User Equipment) has camped on a cell and registered on the network, but it is in the idle mode. This is the normal state when the modem is connected to the network.CONNECT
: the modem is in the frame transmitting/receiving state.
The values meaning for the element 1 of the tuple, the access technology, are:
No Service
: the modem is not connected to the cell.GSM
: the modem is connected using GSM technology.GPRS
: the modem is connected using GPRS technologyEDGE
: the modem is connected using EDGE technologyeMTC
: the modem is connected using eMTC technologyNB-IoT
: the modem is connected using NB-IoT technology
Classes¶
Class GNSS
¶
This class is used to interface with GNSS hardware submodule of the cellular system. Note that the start()
method has to be called in order to start the GNSS subsystem.
Class methods¶
method start
¶
start()
fix()
or location()
methods have to be called. method fix
¶
fix(timeout=60)
timeout
argument is expressed in seconds and is the max amount of time to wait for the fix to complete. The default value is 60 seconds. When the timeout expires, the GNSSTimeoutError exception is raised. The returned tuple is composed by the following elements:
Float
: The latitude expressed as (-)dd.ddddd degreesFloat
: The longitude expressed as (-)ddd.ddddd degreesFloat
: The horizontal dilution of precisionFloat
: The altitude above/below mean sea level, expressed in meters.Integer
: GNSS positioning mode. 2: 2D positioning, 3: 3D positioning.Float
: Course Over Ground based on true north, expressed as ddd.mm (ddd: degrees, mm: minutes).Float
: Speed over ground, expressed as Km/h.Float
: Speed over ground, expressed as knots.Integer
: Number of fixed satellites.
NOTE 1: The Cellular hardware module on the 4ZeroBox Mobile and on the EXP-CONNECT board can use one of the GNSS or GSM subsystem at a time. While the fix request is ongoing, the GSM connection gets suspended. Long timeouts in a condition of low GNSS antenna reception may cause the GSM connection to drop; the cellular software module will auto reconnect as soon as it is possible after fix completes. See also disable() method and enable() method to disable and enable the GNSS fix operations.
NOTE 2: With the cellular hardware module on the 4ZeroBox Mobile and on the EXP-CONNECT board, the very first fix done after the GNSS submodule startup may requires longer time (at least 30 seconds, the better GNSS antenna reception, the shorter the fix). Additional fixes done afterwards require shorter timings (at least 3 seconds).
method location
¶
location(timeout=60)
timeout
argument is expressed in seconds and is the max amount of time to wait for the fix to complete. The default value is 60 seconds. When the timeout expires, the GNSSTimeoutError exception is raised. The returned tuple is composed by the following elements:
Float
: The latitude expressed as (-)dd.ddddd degreesFloat
: The longitude expressed as (-)ddd.ddddd degreesFloat
: The altitude above/below mean sea level, expressed in meters.
NOTE: see the fix() method notes for GNSS fix operation details.
method disable
¶
disable()
fix()
or location()
return with last known fix data, without doing any actual hardware fix operation. method enable
¶
enable()
Names¶
gnss
¶
gnss
GNSS
class. Examples¶
Using the cellular with 4ZeroBox Mobile:¶
from bsp import board
from networking import cellular
board.init()
board.summary()
try:
print("configuring cellular...")
# Use a Zerynth SIM
cellular.configure()
print("initializing modem...")
cellular.init()
print("imei: ", cellular.imei())
print("imsi: ", cellular.imsi())
print("SIM ID: ", cellular.iccid())
print("Initializing the GPS...")
cellular.gnss.start()
print("connecting...")
cellular.start()
print("connected!")
print("ppp info: :", cellular.info())
print("cell info: ", cellular.cellinfo())
ip=cellular.resolve("www.zerynth.com")
print("www.zerynth.com resolved ip: ", ip)
# sleep a little bit
sleep(5000)
print("Disconnecting...")
cellular.stop()
print("Disconnected!")
print("Get GPS data...")
print("GPS :", cellular.gnss.fix())
cellular.deinit()
except CellularBadAPN:
print("Bad APN")
cellular.stop()
cellular.deinit()
except CellularException:
print("Generic Cellular Exception")
cellular.stop()
cellular.deinit()
except GNSSTimeoutError:
print("GPS fix timed out")
cellular.deinit()
except Exception as e:
print("Exception: ", e)
cellular.stop()
cellular.deinit()
raise e
while True:
sleep(1000)
Using the cellular with ZM1-DB + EXP-CONNECT board¶
from bsp import board
from networking import cellular
# Import the module for EXP-CONNECT board.
from expansions import connect
board.init()
board.summary()
# Initialize the EXP-CONNECT board.
board.next_expansion(connect, (0,))
try:
print("configuring cellular...")
# Use the APN for a custom SIM
cellular.configure(apn="my-provider-apn")
print("initializing modem...")
cellular.init()
print("IMEI: ", cellular.imei())
print("IMSI: ", cellular.imsi())
print("SIM ID: ", cellular.iccid())
print("Initializing the GNSS...")
cellular.gnss.start()
print("connecting...")
cellular.start()
print("connected!")
print("ppp info: :", cellular.info())
print("cell info: ", cellular.cellinfo())
ip=cellular.resolve("www.zerynth.com")
print("www.zerynth.com resolved ip: ", ip)
# sleep a little bit
sleep(5000)
print("Disconnecting...")
cellular.stop()
print("Disconnected!")
print("Get GPS data...")
print("GPS :", cellular.gnss.fix())
cellular.deinit()
except CellularBadAPN:
print("Bad APN")
cellular.stop()
cellular.deinit()
except CellularException:
print("Generic Cellular Exception")
cellular.stop()
cellular.deinit()
except GNSSTimeoutError:
print("GPS fix timed out")
cellular.deinit()
except Exception as e:
print("Exception: ", e)
cellular.stop()
cellular.deinit()
raise e
while True:
sleep(1000)
Terms and Abbreviations¶
Abbreviation | Description |
---|---|
APN | Access Point Name |
DHCP | Dynamic Host Configuration Protocol |
DNS | Domain Name Server |
EDGE | Enhanced Data rates for GSM Evolution |
GNSS | Global navigation satellite system |
GPRS | General Packet Radio Service |
GPS | Global Positioning System |
GSM | Global System for Mobile communications |
IMEI | International Mobile Equipment Identity |
IMSI | International Mobile Subscriber Identity |
MAC | Media Access Control |
MCC | Mobile Country Code |
MNC | Mobile Network Code |
NB-IoT | Narrow Band for Internet of Things |
PPP | Point-to-Point Protocol |
RSSI | Received Signal Strength Indicator |
SIM | Subscriber Identity Module |
UE | User Equipment |
eMTC | enhanced Machine Type Communication |