cwalter-at/freemodbus: a community maintained Modbus slave stack with three licences in one tree

A fork that publishes its own risk

The first paragraph of this README is unusual, because it explains the project's governance before describing the code. The project sees little to no activity from the original creators, yet it remains popular, so the stated approach is to try a more open and courageous way forward, welcoming everyone to participate, create pull requests and contribute in any way.

The conditions come with an explicit warning. Pull requests will be merged if properly justified and there is no pushback from the community, and it is understood that bugs and errors may enter the codebase with that approach. The README then does something few forks do: it names the fallback. Version 1.6.0 by Christian Walter is described as the latest official release, so you always have the option to use either `master` or `1.6.0`.

That is a coherent position, and it is the honest description of a volunteer maintained fork of a project that was written for a different era. The `Changelog.txt` at the top level is where the divergence from the original line shows up, and the last push to the repository was on 2026-09-17, with v1.6.0 published on 2025-05-30 as the latest release. So the fork is being worked on, and it is not cutting releases at the same rate.

What the stack actually implements

FreeModbus is a Modbus ASCII and RTU and Modbus TCP implementation for embedded systems. It provides an implementation of the Modbus Application Protocol v1.1a and supports both the RTU and ASCII transmission modes as defined in the Modbus over serial line specification 1.0.

The version numbers in those specifications matter more than they might look. The Application Protocol v1.1a and the serial line specification 1.0 are the documents the implementation follows, and they are old ones. That means the register model, the function code set and the frame format are the classic Modbus ones, with no vendor extension layer and no newer protocol revisions in scope. For a device that has to talk to an existing supervisory system, that is exactly what you want, because it is what the system expects.

The repository's own description calls it a slave implementation, and that is the role it plays on the bus: it answers requests from a master rather than initiating them. The transport options are the three usual ones, RTU for binary serial links, ASCII for human readable serial, and TCP for Ethernet.

Documentation is inherited rather than rewritten. Complete documentation of the original FreeModbus implementation can be found in the `doc/html` directory in the repository, so the reference material describes the original project as it stood, and the fork's own additions are not covered by it. That is worth keeping in mind when you read an example, because the code may have moved on from the text.

Three licences in one tree

FreeModbus uses a multi-license approach, and the structure is organised by directory, which is unusual enough to be worth reading carefully before you copy a file.

The core protocol stack, in the `modbus/` directory, is under the BSD License. The port implementations, which live in the `demo/*/port/` directories, are generally LGPL. The demo applications, in the `demo/*/` directories, are generally GPL. The tree ships the three licence texts as `bsd.txt`, `lgpl.txt` and `gpl.txt` at the top level.

The project explains what that structure is for. It allows using the core protocol stack in both open source and proprietary applications under BSD, using the port implementations in proprietary applications with some restrictions under LGPL, and using the demo applications only in GPL compatible projects under GPL. And the instruction to always check the licence header in individual source files takes priority over the general description, because the words generally are doing work there.

The practical consequence for a commercial device is that the boundary you care about is the `port/` directory of the demo you use. The Modbus state machine and the frame handling are BSD and easy to reuse. The board support layer around them is usually LGPL, which is a weaker copyleft than GPL but still a condition. The example application on top is GPL, and a demo main loop is often the first thing an engineer copies, which is exactly the file that cannot go into a proprietary product.

This article does not interpret the obligations for your product. Read the headers of the files you actually copy, and the licence files in the repository, and treat the layering as a map of where the questions will be.

The demo directory is the board support catalogue

The `demo/` directory is the widest part of the repository, and it is a catalogue of ports rather than a set of tutorials. The listed directories include `ADUC7XXX`, `AT91SAM7X_ROWLEY`, `ATSAM3S`, `ATSAM3S_FREERTOS`, `AVR`, `AVR2560`, `BARE`, `HCS08`, `LINUX`, `LINUXTCP`, `LPC214X`, `MCF5235`, `MCF5235CW`, `MCF5235TCP`, `MSP430`, `STM32_CMAKE`, `STR71X`, `STR71XGCC`, `STR71XTCP`, `WIN32`, `WIN32TCP` and `Z8ENCORE`.

That list is the reason to use this project at all. A Modbus slave needs a UART, a timer for the RTU frame gap, and a way to hold the register map, and the vendor specifics live in the port layer. Rather than writing that for an AT91SAM7X or an MSP430 or an STM32 by hand, you take an existing port and adapt it.

The naming convention is informative. The plain names such as `LINUX`, `WIN32`, `BARE` and `AVR` are single chip families or hosts. The `TCP` suffix marks the Ethernet variants, where `LINUXTCP`, `WIN32TCP`, `MCF5235TCP` and `STR71XTCP` are the Modbus TCP ports, and the serial and TCP ports are separate pieces of work because the transport and the frame timing differ. The `FREERTOS` and `_CMAKE` and `_GCC` suffixes point at the operating system and the build system the port expects, which tells you the ports are not uniform and each one carries its own assumptions about the toolchain and the timer setup.

The `BARE` directory is the one to look at if you want a minimal starting point with no vendor specifics, and the `AVR` and `STM32_CMAKE` ones if you are on one of those platforms.

Building the core and using the tools directory

The repository has a `CMakeLists.txt` at the top level, a `tools/` directory and the `modbus/` core, so a build goes through CMake with the port you want selected, and the `tools/` directory holds the supporting utilities that come with the project.

The important part for a new user is the difference between the core and the demo. The core in `modbus/` is the protocol implementation, and it is the part that is BSD licensed and reusable on its own. The demo directories are complete applications, each pairing a port with an example program. That means you can take the core, and write only the port layer for your board, or take a whole demo and strip it back.

Neither route is documented in the README itself. The complete documentation lives in the `doc/html` directory and describes the original implementation, so the build instructions you will find there are for the original project layout. This is the general condition of a community maintained fork: the code is the authority and the documentation is a snapshot from an earlier era, and a prospective user should expect to spend time reading source rather than a tutorial.

The `Changelog.txt` file and the repository's release list are the more useful orientation tools for a fork, since the changelog shows what has changed relative to the original line and the tags show what is considered stable enough to publish.

Where a Modbus slave library is the wrong answer

The first wrong case is a master. The project's description is a slave implementation, and there is no indication in the repository that master side functionality is provided, so if your device has to poll a sensor or a meter rather than answer a supervisor, this is the wrong codebase.

The second is a protocol beyond classic Modbus. The implementation follows the Application Protocol v1.1a and the serial line specification 1.0, with RTU, ASCII and TCP. If the requirement involves any other Modbus variant, or a modern industrial Ethernet protocol with a different object model, none of that is in scope.

The third is a safety or security critical device that needs a maintained upstream with a fix commitment. This is a fork of a project whose original creators are inactive, where pull requests are merged precisely because a maintainer is available to review them, and where the project itself warns that errors may enter. The mitigations are real, in that the 1.6.0 tag gives you a known good point, but the honest characterisation is that you are taking maintenance responsibility for whatever you ship.

The fourth is a device with a genuine security requirement. The specifications the library follows predate most of the attention paid to industrial protocol security, and the repository text says nothing about authentication, authorisation or transport protection for a serial Modbus link, so those concerns have to be handled outside the library, or by choosing a different protocol.

Editorial conclusion

Adopt this FreeModbus fork when you are writing a Modbus slave on a microcontroller and want the original, widely ported implementation with the board support already present, and you are comfortable taking the risk the README names, namely that bugs and errors may enter the codebase because pull requests are merged when justified. Do not adopt it as a maintained upstream project with a guaranteed fix path, since the original creators are inactive and the newest official release is 1.6.0 from 2025-05-30, and do not adopt the demo applications in a proprietary product, because they are GPL licensed. Verify first which licence applies to the exact port you plan to use, since the port implementations are generally LGPL and the demos are generally GPL, and decide deliberately whether to track `master` or the 1.6.0 release.

Frequently asked questions

Official sources

1. cwalter-at/freemodbus on GitHub
2. Issues
3. README
4. Releases