NB-IoT Unit

NB-IOT Unit 是一款适用于全球 Cat-NB 频段的无线通信模块。它内置 SIM7020G 通信模块，使用串行通信（AT 指令集控制）。

支持以下产品：

备注

使用前请确保设备支持您所在地区的 NB-IoT 频段。

备注

请确保 SIM7020 的固件版本大于或等于 1752B12SIM7020C。

可用于检查固件版本。

UiFlow2 应用示例

NBIoT HTTP 应用示例

在 UiFlow2 中打开 cores3_unit_nbiot_http_example.m5f2 项目。

该示例演示如何使用 NBIoT Unit 发送 HTTP 请求。

点击 Send 按钮发送 HTTP 请求。响应数据将打印在文本区域中。

UiFlow2 代码块：

示例输出：

在屏幕上输出接收到的 NBIoT 消息数据。

MQTT 示例

在 UiFlow2 中打开 cores3_unit_nbiot_mqtt_example.m5f2 项目。

该示例演示如何使用 NBIoT Unit 发送 MQTT 消息。

UiFlow2 代码块：

示例输出：

在屏幕上输出接收到的 NBIoT 消息数据。

MicroPython 应用示例

NBIoT HTTP 应用示例

该示例演示如何使用 NBIoT Unit 发送 HTTP 请求。

点击 Send 按钮发送 HTTP 请求。响应数据将打印在文本区域中。

MicroPython 代码块：

# SPDX-FileCopyrightText: 2026 M5Stack Technology CO LTD
#
# SPDX-License-Identifier: MIT

import os, sys, io
import M5
from M5 import *
import m5ui
import lvgl as lv
from unit import NBIOTUnit


page0 = None
label0 = None
label1 = None
button0 = None
textarea0 = None
textarea1 = None
nbiot_0_http_req = None
nbiot_0 = None


def button0_short_clicked_event(event_struct):
    global page0, label0, label1, button0, textarea0, textarea1, nbiot_0_http_req, nbiot_0
    nbiot_0_http_req = nbiot_0.post(
        "http://httpbin.org/post",
        json={"message": "Hello from M5Stack!", "status": "active"},
        headers={
            "Content-Type": "application/json",
            "Custom-Header": "MyHeaderValue",
        },
    )
    textarea1.set_text(str(nbiot_0_http_req.text))


def button0_event_handler(event_struct):
    global page0, label0, label1, button0, textarea0, textarea1, nbiot_0_http_req, nbiot_0
    event = event_struct.code
    if event == lv.EVENT.SHORT_CLICKED and True:
        button0_short_clicked_event(event_struct)
    return


def setup():
    global page0, label0, label1, button0, textarea0, textarea1, nbiot_0_http_req, nbiot_0

    M5.begin()
    Widgets.setRotation(1)
    m5ui.init()
    page0 = m5ui.M5Page(bg_c=0xFFFFFF)
    textarea0 = m5ui.M5TextArea(
        text="http://httpbin.org/post",
        placeholder="Placeholder...",
        x=46,
        y=10,
        w=195,
        h=21,
        font=lv.font_montserrat_14,
        bg_c=0xFFFFFF,
        border_c=0xE0E0E0,
        text_c=0x212121,
        parent=page0,
    )
    textarea1 = m5ui.M5TextArea(
        text="textarea1",
        placeholder="Placeholder...",
        x=10,
        y=68,
        w=300,
        h=162,
        font=lv.font_montserrat_14,
        bg_c=0xFFFFFF,
        border_c=0xE0E0E0,
        text_c=0x212121,
        parent=page0,
    )
    label0 = m5ui.M5Label(
        "url:",
        x=10,
        y=10,
        text_c=0x000000,
        bg_c=0xFFFFFF,
        bg_opa=0,
        font=lv.font_montserrat_16,
        parent=page0,
    )
    label1 = m5ui.M5Label(
        "Response",
        x=10,
        y=44,
        text_c=0x000000,
        bg_c=0xFFFFFF,
        bg_opa=0,
        font=lv.font_montserrat_14,
        parent=page0,
    )
    button0 = m5ui.M5Button(
        text="Send",
        x=251,
        y=10,
        bg_c=0x2196F3,
        text_c=0xFFFFFF,
        font=lv.font_montserrat_14,
        parent=page0,
    )

    button0.add_event_cb(button0_event_handler, lv.EVENT.ALL, None)

    textarea0.set_one_line(True)
    page0.screen_load()
    nbiot_0 = NBIOTUnit(1, port=(18, 17), verbose=False)
    nbiot_0.connect(apn="cmnbiot")
    while not (nbiot_0.isconnected()):
        pass


def loop():
    global page0, label0, label1, button0, textarea0, textarea1, nbiot_0_http_req, nbiot_0
    M5.update()


if __name__ == "__main__":
    try:
        setup()
        while True:
            loop()
    except (Exception, KeyboardInterrupt) as e:
        try:
            m5ui.deinit()
            from utility import print_error_msg

            print_error_msg(e)
        except ImportError:
            print("please update to latest firmware")

示例输出：

在屏幕上输出接收到的 NBIoT 消息数据。

MQTT 示例

该示例演示如何使用 NBIoT Unit 发送 MQTT 消息。

MicroPython 代码块：

# SPDX-FileCopyrightText: 2026 M5Stack Technology CO LTD
#
# SPDX-License-Identifier: MIT

import os, sys, io
import M5
from M5 import *
import m5ui
import lvgl as lv
from unit import NBIOTUnit


page0 = None
label0 = None
nbiot_0_mqtt = None
nbiot_0 = None


def nbiot_0__testtopic_a_event(data):
    global page0, label0, nbiot_0_mqtt, nbiot_0
    label0.set_text(str(data[1]))


def setup():
    global page0, label0, nbiot_0_mqtt, nbiot_0

    M5.begin()
    Widgets.setRotation(1)
    m5ui.init()
    page0 = m5ui.M5Page(bg_c=0xFFFFFF)
    label0 = m5ui.M5Label(
        "label0",
        x=130,
        y=105,
        text_c=0x000000,
        bg_c=0xFFFFFF,
        bg_opa=0,
        font=lv.font_montserrat_14,
        parent=page0,
    )

    page0.screen_load()
    nbiot_0 = NBIOTUnit(1, port=(18, 17), verbose=False)
    nbiot_0.connect(apn="cmnbiot")
    while not (nbiot_0.isconnected()):
        pass
    nbiot_0_mqtt = nbiot_0.MQTTClient(
        "uiflow2-client", "mqtt.m5stack.com", port=1883, user="", password="", keepalive=0
    )
    nbiot_0_mqtt.connect(clean_session=False)
    nbiot_0_mqtt.subscribe("testtopic/a", nbiot_0__testtopic_a_event, qos=0)


def loop():
    global page0, label0, nbiot_0_mqtt, nbiot_0
    M5.update()
    nbiot_0_mqtt.check_msg()


if __name__ == "__main__":
    try:
        setup()
        while True:
            loop()
    except (Exception, KeyboardInterrupt) as e:
        try:
            m5ui.deinit()
            from utility import print_error_msg

            print_error_msg(e)
        except ImportError:
            print("please update to latest firmware")

示例输出：

在屏幕上输出接收到的 NBIoT 消息数据。

API参考

class unit.nbiot.NBIOTUnit(uart_or_id, port=None, verbose=False)

基类：SIM7020

创建一个 NBIOTUnit 对象。

参数:

uart_or_id (machine.UART | int) – UART 对象或 UART ID。
port (list | tuple) – 包含 RX 和 TX 引脚编号的 list 或 tuple。若 uart_or_id 为 ID，则必填。
verbose (bool) – 是否打印调试信息。

UiFlow2 代码块：

MicroPython 代码块：

from unit import NBIOTUnit
import machine

# Using UART ID and pins (rx, tx)
nbiot = NBIOTUnit(1, (16, 17))

# Or using UART object
uart = machine.UART(1, tx=17, rx=16)
nbiot = NBIOTUnit(uart)

connect(apn='cmnbiot')

连接到 NB-IoT 网络。

参数:: apn (str) – NB-IoT 网络的 APN。默认值为 “cmnbiot”。

UiFlow2 代码块：

MicroPython 代码块：

nbiot.connect("cmnbiot")

isconnected()

检查 NB-IoT 单元是否已连接到网络。

返回:: 如果已连接则为 True，否则为 False。
返回类型:: bool

UiFlow2 代码块：

MicroPython 代码块：

if nbiot.isconnected():
    print("NB-IoT unit is connected")
else:
    print("NB-IoT unit is not connected")

active(en)

激活或停用 NB-IoT 单元。停用后将进入低功耗模式。

参数:: en (bool) – True 为激活，False 为停用。

UiFlow2 代码块：

MicroPython 代码块：

nbiot.active(True)

status([param])

获取 NB-IoT 单元的状态。

以下是常用的支持参数。

Parameter	Description
RSSI	信号强度
pin	SIM 卡状态
station	站点注册状态

参数:: param (str) – 用于指定状态类型的可选参数。
返回:: 状态信息。
返回类型:: str | tuple

UiFlow2 代码块：

MicroPython 代码块：

# get signal strength
print(nbiot.status("rssi"))

# get SIM Card status
print(nbiot.status("pin"))

# get station registration status
print(nbiot.status("station"))

ifconfig()

获取 IP 级网络接口参数：IP 地址、子网掩码、网关和 DNS 服务器。

返回:: 包含网络接口参数的元组。
返回类型:: tuple

UiFlow2 代码块：

MicroPython 代码块：

# Get IP address
print(nbiot.ifconfig()[0])
# Get subnet mask
print(nbiot.ifconfig()[1])
# Get gateway
print(nbiot.ifconfig()[2])
# Get DNS server
print(nbiot.ifconfig()[3])

config('param')

config(param=value)

获取或设置 NB-IoT 单元的配置参数。

以下是常用的支持参数。

Parameter	permissions	Description
APN（Access Point Name）：接入点名称，用于配置蜂窝网络（2G/3G/4G/LTE/5G）设备连接运营商数据网络的参数。通常包含运营商的 APN 名称，必要时还包括用户名、密码、认证方式等。	R	接入点名称
mode	R	网络模式（仅支持 NB-IoT）
band	读/写	频段
ccid	R	SIM 卡 CCID
imei	R	设备 IMEI
IMSI（International Mobile Subscriber Identity，国际移动用户识别码）是用于唯一标识蜂窝网络用户/USIM/SIM 的号码，通常由 15 位数字组成：MCC（移动国家码）+ MNC（移动网络码）+ MSIN（移动用户识别码）。	R	SIM 卡 IMSI
mfr 通常是 manufacturer（制造商）的缩写；在一些语境下也可能指 manufacturing（制造/生产）。	R	Manufacturer
model	R	模块型号
version	R	固件版本

参数:

param (str) – 要获取或设置的配置参数。
value – 用于设置配置参数的值。

返回:

获取时配置参数的值。

返回类型:

None | str | int | tuple

UiFlow2 代码块：

MicroPython 代码块：

# Get apn
print(nbiot.config('apn'))

# Get network mode
nbiot.config('mode')

# Get Frequency Band
nbiot.config('band')

# Set Frequency Band
nbiot.config(band=(1, 3, 5, 8))

# Get CCID
nbiot.config('ccid')

# Get IMEI
nbiot.config('imei')

# Get IMSI
nbiot.config('imsi')

# Get Manufacturer
nbiot.config('mfr')

# Get Module Model
nbiot.config('model')

# Get Firmware Version
nbiot.config('version')

request(method, url, data=None, json=None, headers={}, stream=None, auth=None, timeout=None, parse_headers=True)

head(url, **kw)

get(url, **kw)

post(url, **kw)

put(url, **kw)

patch(url, **kw)

delete(url, **kw)

发送 HTTP 请求。

参数:

method (str) – 要使用的 HTTP 方法（例如 “GET”、”POST”）。
url (str) – 用于发送请求的 URL。
data – （可选）用于在 Request 请求体中发送的字典、元组列表、bytes 或类文件对象。
json – （可选）要在 Request 的正文中发送的可 JSON 序列化的 Python 对象。
headers (dict) – （可选）要随请求一起发送的 HTTP Headers 字典。
stream (bool) – （可选）如果为 False，响应内容将立即下载。
auth (tuple) – （可选）用于启用 Basic/Digest/Custom HTTP Auth 的 Auth 元组。
timeout (float) – （可选）在放弃之前等待服务器发送数据的秒数。
parse_headers (bool) – （可选）是否解析响应头。

返回:

一个 Response 对象。

备注

更多详情请参见 requests2。

UiFlow2 代码块：

MicroPython 代码块：

# GET request
response = nbiot.get("http://httpbin.org/get")
print(response.status_code)
print(response.text)
response.close()

# POST request with JSON data
response = nbiot.post("http://httpbin.org/post", json={"key": "value"})
print(response.json())
response.close()

MQTTClient(client_id, server, port=0, user=None, password=None, keepalive=0, ssl=False, ssl_params={})

创建一个 MQTT 客户端。

参数:

client_id (str) – 唯一的客户端 ID 字符串。
server (str) – 远程 broker 的主机名或 IP 地址。
port (int) – 要连接的服务器主机的网络端口。默认为 0。
user (str) – 用于认证的用户名。
password (str) – 用于认证的密码。
keepalive (int) – 允许与 broker 通信之间的最大时间间隔（以秒为单位）。默认值为 0。
ssl (bool) – 是否使用 SSL/TLS 支持。默认值为 False。
ssl_params (dict) – SSL/TLS 参数。

返回:

一个 MQTTClient 对象。

备注

详情请参见 MQTTClient 。

UiFlow2 代码块：

MicroPython 代码块：

mqtt = nbiot.MQTTClient("client_id", "mqtt.m5stack.com", port=1883, user="user", password="password")
mqtt.connect()
mqtt.publish("topic", "message")
mqtt.subscribe("topic", lambda topic, msg: print(topic, msg))
mqtt.check_msg()