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 value BG95_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()

function stop¶

stop()

function resolve¶

resolve(host, name="cellular")

function info¶

info(name="cellular")

1. Bool: DHCP enabled (True) or disabled (False)
2. String: IP address
3. String: netmask
4. String: gateway
5. String: DNS
6. String: MAC address

function interface¶

interface(name="cellular")

function atmode¶

atmode()

function pppmode¶

pppmode()

function imei¶

imei()

function imsi¶

imsi()

function iccid¶

iccid()

function rssi¶

rssi()

function cellinfo¶

cellinfo()

1. String: The state of the modem connection. Can be: SEARCH, LIMSRV, NOCONN, CONNECT.
2. String: Access technology. Can be: No Service, GSM, GPRS, EDGE, eMTC, NB-IoT.
3. String: Operator code. 3 chars for MCC, 3 chars for MNC.
4. String: Selected band
5. Integer: Channel ID
6. Integer: Local Area Code
7. Integer: Cell ID
8. Integer: Base station ID code
9. Integer: Operator MCC
10. Integer: Operator MNC
11. String: 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 mode
• LIMSRV: 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 technology
• EDGE: the modem is connected using EDGE technology
• eMTC: the modem is connected using eMTC technology
• NB-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()

method fix¶

fix(timeout=60)

The returned tuple is composed by the following elements:

1. Float: The latitude expressed as (-)dd.ddddd degrees
2. Float: The longitude expressed as (-)ddd.ddddd degrees
3. Float: The horizontal dilution of precision
4. Float: The altitude above/below mean sea level, expressed in meters.
5. Integer: GNSS positioning mode. 2: 2D positioning, 3: 3D positioning.
6. Float: Course Over Ground based on true north, expressed as ddd.mm (ddd: degrees, mm: minutes).
7. Float: Speed over ground, expressed as Km/h.
8. Float: Speed over ground, expressed as knots.
9. 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)

The returned tuple is composed by the following elements:

1. Float: The latitude expressed as (-)dd.ddddd degrees
2. Float: The longitude expressed as (-)ddd.ddddd degrees
3. Float: The altitude above/below mean sea level, expressed in meters.

NOTE: see the fix() method notes for GNSS fix operation details.

method disable¶

disable()

method enable¶

enable()

Names¶

gnss¶

gnss

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¶