Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/t0ha/uprotobuf
Google Protobuf implementation for MicroPython 1.17+
https://github.com/t0ha/uprotobuf
Last synced: about 1 month ago
JSON representation
Google Protobuf implementation for MicroPython 1.17+
- Host: GitHub
- URL: https://github.com/t0ha/uprotobuf
- Owner: T0ha
- License: mit
- Created: 2022-04-19T09:53:58.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2022-07-22T16:21:06.000Z (over 2 years ago)
- Last Synced: 2023-04-04T02:41:46.527Z (over 1 year ago)
- Language: Python
- Size: 29.3 KB
- Stars: 6
- Watchers: 2
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Google Protobuf implementation for MicroPython 1.17+
This library in inspired by [micropython-uprotobuf](https://github.com/jazzycamel/micropython-uprotobuf) and [ExProtobuf](https://github.com/elixir-protobuf/protobuf).
The main goal is to implement [Google Protocol buffers](https://developers.google.com/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
```shell
$ 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:
```protobuf
syntax = "proto2"
package animal;
message Animal {
optional string name = 1;
}
```
To generate `animal_upb2.py` run
```shell
$ 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:
```shell
$ 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.
```bash
$ 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:
```bash
$ 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:
```python
import unittest
unittest.main('tests')
```
This will do the job.
If you have any issues or suggestions, you are welcome.