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 引脚号的列表或元组。如果 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	R	接入点名称
mode	R	网络模式（仅支持 NB-IoT）
band	R/W	频段
ccid	R	SIM 卡 CCID
imei	R	设备 IMEI
imsi	R	SIM 卡 IMSI
mfr	R	制造商
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 – (可选) 要在请求体中发送的字典、元组列表、字节或类文件对象。
json – (可选) 要在请求体中发送的 JSON序列化的 Python 对象。
headers (dict) – (可选) 随请求发送的 HTTP 头字典。
stream (bool) – (可选) 如果为 False，响应内容将被立即下载。
auth (tuple) – (可选) 用于启用 Basic/Digest/Custom HTTP 认证的元组。
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) – 远程代理的主机名或 IP 地址。
port (int) – 要连接的服务器主机网络端口。默认是 0。
user (str) – 认证用的用户名。
password (str) – 认证用的密码。
keepalive (int) – 与代理通信之间允许的最大秒数。默认为 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()