Google Protobuf implementation for MicroPython 1.17+

This library in inspired by micropython-uprotobuf and ExProtobuf.

The main goal is to implement Google Protocol buffers for MicroPython and embedded systems.

Main ideas

• KISS and ideomatic code base
• Embedded code (including autogenerated) should be as small and quick as possible
• Pure python code
• Should work on as much devices as possible

Prerequisites

• python 3.9+
• micropython 1.17+ (not tested on earlier versions)
• GNU Make
• protoc 3.19+ (not tested on earlier versions)
• asdf (preferably)

Usage

Generating Python classes for ProtoBuf

	$ protoc --plugin=protoc-gen-custom=scripts/uprotobuf_plugin.py \
           --custom_out={OUTPUT_PATH} \
           {PATH_TO_PROTO_FILE}

This will generate file(s) like {OUTPUT_PATH}/{PROTO_FILE_NAME}_upb2.py.

Using protobuf classes on controller

Copy your generated files and protobuf/uprotobuf.py to flash of your controller. Now you can use your generated classes in your code.

Example:

animal.proto:

syntax = "proto2"

package animal;

message Animal {
  optional string name = 1;
}

To generate animal_upb2.py run

	$ protoc --plugin=protoc-gen-custom=scripts/uprotobuf_plugin.py \
           --custom_out=. \
           animal.proto

Now you can start MicroPython shell and try:

import animal_upb2
animal = animal_upb2.Animal()

animal.name = "Dog"

encoded_message = animal.encode() 
animal1 = Animal.decode(encoded_message)

Supported features

• Protobuf 2 syntax
• Scalar types encoding and decoding with implicit and explicit defaults
• Nested messages
• Message type fields
• Enums without implicit default value
• Repeated fields (partly implemented)

TODO

• Protobuf 3 syntax
• Repeated fields complete and test (including packed)
• Test message fields
• OneOf fields
• Maps

Groups won't be implemented since they are considered depricated. Required fields check is not implemented for now in favour of efficiency.

Tested hardware

• PC (Mac)
• ESP32-wroom
• ESP8266 (LoLin V3)

Pls, add your hardware if you have tested.

Testing

To test locally run the following command:

$ make clean tests

This will generate all needed classes for python3 and MicroPython, run tests on both of them.

Testing on Device

For testing on device you need Adafruite Ampy to be installed.

$ python3 -m pip install adafruit-ampy

This works and tested for ESP32 and ESP8266 device family. If you are willing to test on other devices, please, you are welcome to update.

To upload files to your device connect it via USB and run:

$ make test-dev

This will upload all nesessary files to the board. Then connect to your device with REPL and run the following in it:

import unittest
unittest.main('tests')

This will do the job.

If you have any issues or suggestions, you are welcome.