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")
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.
If dhcp
is True (the default) other following four IP related arguments are ignored. When dhcp
is False, the four IP related arguments are:
ip
: is the IP address.mask
: the net mask expressed as A.B.C.D dotted address.gateway
: the gateway to be used as default router.-
dns
: the Domain Name Server to be used for name resolution. Default is "8.8.8.8", the Google DNS. -
timeout
: Connection timeout in milliseconds.CellularException
is raised if connection do not succeed during this time. Default value 10000 ms. modem_type
: the Cellular hardware module type. Default valueBG95_M3
.name
: the interface name to be used in a multi interface scenario. Default value "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 |