Metadata-Version: 2.4
Name: EmbeddedProto
Version: 4.0.0b3
Summary: EmbeddedProto generator
Author-email: "Embedded AMS B.V." <info@EmbeddedAMS.nl>
License-Expression: GPL-3.0-only OR LicenseRef-EmbeddedProto-Commercial
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSES/GPL-3.0-only.txt
License-File: LICENSES/LicenseRef-EmbeddedProto-Commercial.txt
Requires-Dist: Jinja2<4,>=3
Requires-Dist: MarkupSafe<4,>=2.0
Requires-Dist: toposort<2,>=1.7
Requires-Dist: protobuf==7.36.1
Requires-Dist: grpcio-tools==1.83.1
Dynamic: license-file

![alt text](https://embeddedproto.com/wp-content/uploads/2022/04/Embedded_Proto.png "Embedded Proto Logo")


Embedded Proto is a product of Embedded AMS B.V. For more information about Embedded Proto please visit [EmbeddedProto.com](https://EmbeddedProto.com).

Copyright (C) 2020-2026 Embedded AMS B.V. - All Rights Reserved, [www.EmbeddedAMS.nl](https://www.EmbeddedAMS.nl), [info@EmbeddedAMS.nl](mailto:info@EmbeddedAMS.nl)


# Introduction

Embedded Proto is a C++ implementation of [Google Protocol Buffers](https://developers.google.com/protocol-buffers/) dedicated to microcontrollers. The implementation focuses on a small footprint and low memory usage. No dynamic memory allocation is used to make the code predictable. Unit tests and static code analysis are used to improve the reliability of the code.

Natively, protocol buffers are not suitable for microcontrollers. The C++ code protoc generates is written for server and desktop processors. Embedded Proto is a plugin for *protoc* generating C++ code suitable for microcontrollers. In this way, Embedded Proto provides an easy-to-use interface to exchange data between embedded devices and the outside world. Specify the data format between your IoT device and other devices, servers, apps, or desktop applications in a standardized way!


# Requirements

To generate the code for your messages:
* Python 3.11 or newer, and pip.

The protobuf compiler comes with Embedded Proto, you do not have to install protoc yourself.

To build the generated code for your target:
* A C++ compiler supporting C++17.
* No dynamic memory, no exceptions and no RTTI are required. The library is header only.

Optional, for the alternative ways to install described on the [installation](https://EmbeddedProto.com/documentation/installation/) page:
* [uv](https://docs.astral.sh/uv/), a much faster replacement for pip and venv.
* Git, when you use Embedded Proto as a submodule in your project.

Optional, for developing Embedded Proto itself:
* CMake 3.28 or newer, to build and run the unit tests. See [CONTRIBUTING.md](CONTRIBUTING.md).


# Getting started

New to Embedded Proto? Follow the [quick start](https://EmbeddedProto.com/documentation/quick-start/). In about ten minutes you install Embedded Proto, define a message, generate the code for it and serialize the message in a small program on your PC. The same code moves to your microcontroller without changes.

In short, Embedded Proto is installed with pip:
```bash
pip install EmbeddedProto
```
Generate the C++ code for the messages in your \*.proto file:
```bash
embeddedproto -I proto --eams_out=generated proto/reading.proto
```
Build your project with C++17, the `generated` folder and the header only library of Embedded Proto as include paths. The command `embeddedproto --cpp-src-location` prints where the library is.
When linking with a C compiler, do not forget to pass `-lstdc++` to the linker. This prevents errors like `undefined reference to`.

Other ways to install, with uv or as a git submodule, are described on the [installation](https://EmbeddedProto.com/documentation/installation/) page.


# Documentation

The manual lives on [EmbeddedProto.com](https://EmbeddedProto.com/documentation/):
* [How it works](https://EmbeddedProto.com/documentation/how-it-works/)
* [Generating source code](https://EmbeddedProto.com/documentation/generating-source-code/) and [setting field options from a file](https://EmbeddedProto.com/documentation/options-file/)
* [Using a message](https://EmbeddedProto.com/documentation/using-a-message/): strings, bytes, repeated fields, maps, Any and more
* [Serialization](https://EmbeddedProto.com/documentation/serialization/) and [deserialization](https://EmbeddedProto.com/documentation/deserialization/)
* [Supported features](https://EmbeddedProto.com/documentation/supported-features/)
* [Advanced topics](https://EmbeddedProto.com/documentation/advanced-topics/): protobuf editions, callback storage and custom storage

Our website also hosts an array of [examples](https://EmbeddedProto.com/examples/) detailing possible use cases and tutorials on toolchain integrations.


# What is new

Version 4.0.0 is the largest release of Embedded Proto so far. It changes how the library is installed, adds maps, Any and streaming, and supports the new protobuf editions. See [what is new in 4.0](https://EmbeddedProto.com/documentation/what-is-new-in-4-0/) for what you gain, and [migrating from 3.x](https://EmbeddedProto.com/documentation/migrating-from-3-x/) for what to change in your project.

To stay up to date, signup for our [User Update](https://EmbeddedProto.com/signup).


# License

Embedded Proto is dual licensed. See [LICENSE](LICENSE) for the full notice.

## Open source
Embedded Proto is free of charge under the GNU General Public License v3.0. The combined work you distribute must comply with the GPLv3; your own source code may use the GPLv3 or any license compatible with it. The code Embedded Proto generates is produced from templates in this repository and embeds code from them, so the template code in it is covered by the same license. The GPL version comes without support.

## Commercial
Building a closed source product? Then you need a commercial license. It removes the obligation to publish your source code, and depending on the tier includes:
* An unlimited number of MCUs
* Professional support
* A code quality report

See [embeddedproto.com/pricing](https://EmbeddedProto.com/pricing/). Setting your license token is described on the [installation](https://EmbeddedProto.com/documentation/installation/) page.

## Evaluation
Internal evaluation and testing of Embedded Proto before purchase are free and do not require either license, as long as no product containing Embedded Proto or its generated code is distributed.


# Third-party software

For compliance reviews, this is every piece of software Embedded Proto relies on, split by whether it ends up in your product or is only used while generating code.

## In your product
Only code from Embedded Proto itself ends up in your firmware. It contains no third-party code. It does use the C++ standard library, which comes from your own toolchain and is licensed by its vendor, not by Embedded Proto.

| Component | Copyright | License |
| --- | --- | --- |
| Embedded Proto header-only library | Embedded AMS B.V. | GPL-3.0-only OR commercial |
| Generated message code | Embedded AMS B.V. for the template code, you for your `.proto` definitions | GPL-3.0-only OR commercial |
| C++ standard library | The vendor of your toolchain | Whatever your toolchain uses, for example GCC's libstdc++ is GPL-3.0 with the runtime library exception |

## During code generation
These run on your development machine and are not linked into your product. Python comes from your own installation, the packages are installed from PyPI. None of them are redistributed by Embedded Proto.

| Component | Use | License |
| --- | --- | --- |
| [Python](https://www.python.org/) 3.11 or newer | Runs the generator | PSF License |
| [protobuf](https://github.com/protocolbuffers/protobuf) | Parses `.proto` files, `descriptor.proto` is imported by the options file | BSD-3-Clause |
| [grpcio-tools](https://github.com/grpc/grpc) | Bundles the `protoc` compiler | Apache-2.0, bundled protoc is BSD-3-Clause |
| [Jinja2](https://github.com/pallets/jinja) | Renders the code templates | BSD-3-Clause |
| [MarkupSafe](https://github.com/pallets/markupsafe) | Dependency of Jinja2 | BSD-3-Clause |
| [toposort](https://gitlab.com/ericvsmith/toposort) | Orders message definitions | Apache-2.0 |

## Development only
[GoogleTest](https://github.com/google/googletest) (BSD-3-Clause) is a git submodule used for the unit tests of the library. It is not part of the generator package or of your product.


# Development

If you consider helping with the development of Embedded Proto please read [CONTRIBUTING.md](CONTRIBUTING.md) and the [developer section](https://EmbeddedProto.com/documentation/installation/#for-embedded-proto-developers) of the installation page. They detail how you can build the unit tests included in this repo.
