Protobuf：轻量高效的数据序列化利器

物联网设备与云端通信，数据包越小越省流量，解析越快越省电量。JSON虽好用，但冗长的键名和文本格式在资源受限的嵌入式场景下显得笨重。
Protocol Buffers——是由Google开源的二进制序列化协议，以体积小、解析快、跨语言的优势，成为设备端与云端高效通信的首选方案。
合宙LuatOS提供了高效易用的Protobuf核心库：

无需移植第三方代码，直接调用简洁API即可完成结构化数据的编解码，显著降低协议对接复杂度，既省流量又省电量，完美适配嵌入式开发场景，大幅提升通信效率与代码可维护性。

一、Protobuf核心库核心概览

LuatOS的Protobuf核心库支持加载由protoc编译生成的二进制描述文件（.pb），提供完整的数据编码（encode）、数据解码（decode）等功能，支持Proto2和Proto3协议版本，能够根据输入的protobuf定义自动识别并处理相应版本的消息格式，适用于设备与云端、模块间高效数据交换等典型应用场景。

最新API文档详见：https://docs.openluat.com/osapi/core/protobuf/

在LuatOS开发中，使用以下四个函数高效处理Protobuf数据。

1.1  protobuf.load(pbdata)

函数功能：加载Protocol Buffers二进制定义数据到系统中，使其可以用于后续的编码和解码操作。

注意事项：同一个文件只需要加载一次，除非调用过 protobuf.clear() 清除已加载的定义；加载的数据必须是通过protoc.exe程序转换得到的二进制数据。

简要示例：

1--加载 pb文件，这个是从 pbtxt 转换得到的;1
2--下载资源到模块时不需要下载 pbtxt;
3-- 转换命令:protoc.exe -operson.pb person.pbtxt;
4--protoc.exe 下载地址: https://github.com/protocolbuffers/protobuf/releases;
local pb_file = "/luadb/person.pb"
local success, bytesRead = 
if io.exists(pb_file) then
        local success, bytesRead = protobuf.load(io.readFile(pb_file))
        if not success then
            log.info("protobuf", "加载 protobuf 定义失败，已读取 " .. bytesRead .. " 字节")
            return
        else
            log.info("protobuf", "加载 protobuf 定义成功，共解析 " .. bytesRead .. " 字节")
        end
    else
        log.info("protobuf", "pb 文件不存在")
        return
    end

1.2  protobuf.clear()

函数功能：清除已加载的Protocol Buffers二进制定义数据。

注意事项：清除所有定义数据后，可以通过调用protobuf.load()重新加载新的定义数据；清除后，任何依赖已删除类型的序列化/反序列化操作将失败；该函数总是成功执行，没有返回错误的情况。

简要示例：

1--清除所有已加载的定义数据
2. protobuf.clear()
3.log.info("protobuf"，"所有 protobuf 定义已清除")

1.3  protobuf.encode(tpname, data)

函数功能：将符合Protocol Buffer消息定义的Lua表（table）数据，按照指定的消息类型进行序列化，生成二进制编码后的字符串。

注意事项：编码前必须先使用protobuf.load()加载对应的Protocol Buffer定义数据；待编码的table内容必须符合pb文件里的定义；编码结果为二进制字符串，可能包含不可打印字符，调试时建议使用十六进制（如 :toHex()）或Base64查看；如果编码失败，函数会返回nil。

简要示例：

--准备待编编码数据
 local tbdata = {
        name = "wendal",
        id = 123,
        email = "abc@qq.com"
    }
    -- 编码数据；
    local pbdata = protobuf.encode("Person", tbdata)
    if pbdata then
        -- 编码成功，编码后的数据通常包含不可见字符；
        -- 打印长度和十六进制内容（便于调试）；
        log.info("protobuf", "编码成功，数据长度：" .. #pbdata)
        log.info("protobuf", "十六进制内容：" .. pbdata:toHex())
    else
        log.info("protobuf", "编码失败：数据格式或类型不匹配")
    end

1.4  protobuf.decode(tpname, data)

函数功能：将Protocol Buffer二进制编码的数据（字符串）按照指定的消息类型进行反序列化，还原为Lua表（table）结构。

注意事项：在调用此接口前，必须先通过protobuf.load()加载对应的Protocol Buffers定义数据；输入数据data必须是有效的protobuf二进制编码字符串，且与tpname对应的消息格式兼容；Lua table内容无法直接打印出来，建议搭配json.encode()查看。

简要示例：

--假设已通过
--例如通过 protobuf.encode() 生成的返回值变量为 pbdata;
-- 数据解码
 local tbdata = protobuf.decode("Person", pbdata)
 if tbdata then解码后的数据为 Lua table 格式，需要转化为 json 进行显示;log.info("protobuf"，"解码成功，数据内容:"json.encode(tbdata))
--解码后的数据为 Lua table 格式，需要转化为 json 进行显示;
log.info("protobuf"，"解码成功，数据内容:"json.encode(tbdata))
else
log.info("protobuf"，"解码失败")
end

二、开源示例快速上手

理论结合实践，才能更快掌握。完整Protobuf示例已开源在合宙LuatOS官方仓库，你可以直接参考并使用。

以合宙低功耗模组Air780EHV（音频全能系列）为例，可选用配套核心板或开发板快速实操验证。

• 最新示例源码：https://gitee.com/openLuat/LuatOS/tree/master/module/Air780EHM_Air780EHV_Air780EGH/demo/protobuf

• 实操教程详见：https://docs.openluat.com/air780ehv/luatos/app/common/protobuf/

Protobuf示例功能要点：

• 加载protobuf定义文件；

• 将符合protobuf定义的Lua table数据编码为二进制数据；

• 使用json编码同样的Lua table数据后，对比protobuf和json编码后数据的大小；

• 将二进制数据解码为Lua table数据；

• 清除所有已加载的定义数据。

核心代码如下图示，完整demo详见源码仓库最新文件。

本功能模块演示的内容为：
1.加载 protobuf 定义文件；
2.将符合 protobuf 定义的 Lua table 数据编码为二进制数据；
3.使用 json 编码同样的 Lua table 数据后，对比 protobuf 和 json 编码后数据的大小；
4.将二进制数据解码为 Lua table 数据；
5.清除所有已加载的定义数据；


本文件没有对外接口,直接在 main.lua 中 require "protobuf_app" 就可以加载运行；
]]


local function main_task()
    -- 加载 pb 文件, 这个是 proto 经过 protoc.exe 编译后生成的二进制文件
    -- 下载资源到模块时不需要下载 proto 文件
    -- 转换命令: protoc -o person.pb person.proto
    -- protoc.exe 下载地址: https://github.com/protocolbuffers/protobuf/releases
    local pb_file = "/luadb/person.pb"

    local tbdata = {
        name = "wendal",
        id = 123,
        email = "abc@qq.com"
    }

    if io.exists(pb_file) then
        local success, bytesRead = protobuf.load(io.readFile(pb_file))
        if not success then
            log.info("protobuf", "加载 protobuf 定义失败，已读取 " .. bytesRead .. " 字节")
            return
        else
            log.info("protobuf", "加载 protobuf 定义成功，共解析 " .. bytesRead .. " 字节")
        end
    else
        log.info("protobuf", "pb 文件不存在")
        return
    end

    -- 编码数据；
    local pbdata = protobuf.encode("Person", tbdata)
    if pbdata then
        -- 编码成功，编码后的数据通常包含不可见字符；
        -- 打印长度和十六进制内容（便于调试）；
        log.info("protobuf", "编码成功，数据长度：" .. #pbdata)
        log.info("protobuf", "十六进制内容：" .. pbdata:toHex())
    else
        log.info("protobuf", "编码失败：数据格式或类型不匹配")
    end

    -- 对比 protobuf 编码和 json 编码的大小；
    local jdata = json.encode(tbdata)
    if jdata then
        log.info("json", "编码成功，数据长度：" .. #jdata)
        log.info("json", "数据内容：" .. jdata)
    else
        log.info("json", "编码失败：数据格式或类型不匹配")
    end
    -- 可见 protobuffs 比 json 节省很多空间；

    -- 数据解码；
    local tbdata = protobuf.decode("Person", pbdata)
    if tbdata then
        -- 解码后的数据为 Lua table 格式，需要转化为 json 进行显示；
        log.info("protobuf", "解码成功，数据内容：", json.encode(tbdata))
    else
        log.info("protobuf", "解码失败")
    end

    -- 清除所有已加载的定义数据；
    protobuf.clear()
    log.info("protobuf", "所有 protobuf 定义已清除")
end

-- 创建并启动一个 task
-- 用于运行 main_task 函数
sys.taskInit(main_task)

今天的内容就分享到这里了，欢迎加技术交流群共同探讨。

合宙LuatOS提供一站式物联网高效解决方案，集成高速通信、外设驱动、UI交互及视觉处理，助力行业客户快速落地产品，同时实现极致低功耗——相较于传统的“串口屏+DTU方案”或安卓方案，功耗减半，成本不足三分之一。

更多开发资料，详见合宙资料中心：

docs.openluat.com