NB-IoT Unit

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

支持以下产品：

备注

Please ensure that the device supports the NB-IoT frequency bands in your area before use.

备注

Please ensure that the firmware version of SIM7020 is greater than or equal to 1752B12SIM7020C.

can be used to check the firmware version.

UiFlow2 示例

NBIoT HTTP 示例

Open the cores3_unit_nbiot_http_example.m5f2 project in UiFlow2.

This example shows how to send HTTP request using the NBIoT Unit.

click Send button to send HTTP request. Response data will be printed in the textarea.

UiFlow2 代码块：

示例输出：

Output of received NBIoT message data on screen.

MQTT 示例

Open the cores3_unit_nbiot_mqtt_example.m5f2 project in UiFlow2.

This example shows how to send MQTT message using the NBIoT Unit.

UiFlow2 代码块：

示例输出：

Output of received NBIoT message data on screen.

MicroPython 示例

NBIoT HTTP 示例

This example shows how to send HTTP request using the NBIoT Unit.

click Send button to send HTTP request. Response data will be printed in the textarea.

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")

示例输出：

Output of received NBIoT message data on screen.

MQTT 示例

This example shows how to send MQTT message using the NBIoT Unit.

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")

示例输出：

Output of received NBIoT message data on screen.

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