FreeModbus Documentation

FreeModbus is a Modbus implementation designed for embedded systems. It supports the Modbus Application Protocol v1.1a and provides implementations for the following transmission modes:

• Modbus TCP
• Modbus RTU
• Modbus ASCII (over serial line specification 1.0)

FreeRTOS ports are organized into two types of files: core kernel components and hardware/compiler-specific files.

• Core Kernel Components: Every port includes three common files that contain the core kernel logic. These are shared across all ports.
• Hardware/Compiler Specific Files: These files are unique to a specific microcontroller (MCU) or compiler. You only need to include the directories relevant to your target hardware and toolchain.

Example Directory Structure: If you are using the GCC compiler for an ATMega323 microcontroller, you should look in: FreeRTOS/Source/Portable/GCC/ATMega323

When using a FreeRTOS port within this project, the source code is organized into three distinct layers. Understanding this structure is necessary for correctly integrating the kernel and providing microcontroller-specific implementations:

1. Core Kernel Components: Located in FreeRTOS/Source, these three files contain the core kernel logic and are common to every port.
2. Microcontroller/Compiler Specific Files: Located in FreeRTOS/Source/Portable, these files contain the implementations specific to a particular microcontroller or compiler.
3. Kernel Headers: Located in FreeRTOS/Source/include, these files contain the necessary header files for the real-time kernel.

For detailed information on specific implementations, refer to the readme file located within the FreeRTOS/Source/Portable directory.

The FreeRTOS kernel is organized into common core components and hardware-specific portable files.

• Core Kernel Components: Located in FreeRTOS/Source, these files are common to every port:
  • list.c: Core list management.
  • queue.c: Queue implementation.
  • tasks.c: Task management.
  • croutine.c (Optional): Implements co-routine functionality, typically used only on highly memory-constrained systems.
• Hardware/Compiler Specifics: Located in FreeRTOS/Source/Portable. These files contain the implementation specific to a particular microcontroller or compiler.
• Header Files: Located in FreeRTOS/Source/include. This directory contains the real-time kernel header files required for integration.

FreeModbus uses different licenses depending on which part of the repository you are using. This allows for varying levels of integration in proprietary vs. open-source projects:

• Core Protocol Stack (located in modbus/): BSD License. This can be used in both open-source and proprietary applications.
• Port Implementations (located in demo/*/port/): Generally LGPL License. These can be used in proprietary applications with certain restrictions.
• Demo Applications (located in demo/*/): Generally GPL License. These are intended for use only in GPL-compatible projects.

Note: Always check the individual license header in each source file for specific terms.

To use the FreeMODBUS demo on the AT91SAM3S Cortex M3 (SAM3S-EK evaluation kit) via RS485, you must modify the hardware to enable data transmission:

1. Jumper Configuration: Place jumpers on JP11, JP10, and JP12.
2. Solder Modification: Place a solder drop across resistor R25.
3. Pin State: Because RS485 shares data lines with USART1, you must ensure that pin PA23 is set to a high level.

Note on RS485 Biasing: If communication fails or you receive incorrect characters, the RS485 line may not be biased correctly. The SAM3S-EK does not populate bias resistors by default. If your RS485 master does not provide biasing, you must populate resistors R24 and R30 on the bottom side of the PCB.

To build the demo application for the STR71X port using GCC, use the provided Makefile. This port includes complete startup scripts and makefiles designed to work without Rowley Crossworks tools.

Requirements

• GCC Installation: Tested with version 4.1.1.
• C-Library: A working C-Library (e.g., Newlib) is required.
• Hardware: A Wiggler interface is required for debugging.
• Tools: OpenOCD binaries for Windows and Linux are provided in the tools directory.

Build Command

Run the following command in the demo directory to produce the binary:

make all

Once the project is configured in Visual Studio Code:

1. Configure: Open the Command Palette (Ctrl+Shift+P) and run CMake: Configure. Select the Debug configuration.
2. Build: Open the Command Palette and run STM32: Build.
3. Flash: Open the Command Palette and run STM32: Download.

To use the FreeMODBUS demo on an AT91SAM3S Cortex M3 controller with the SAM3S-EK evaluation kit, you must hardware-modify the board to enable RS485 data transmission:

1. Jumper Configuration: Place jumpers on JP11, JP10, and JP12.
2. Solder Modification: Place a solder drop across resistor R25.
3. Pin State Requirement: Because RS485 shares data lines with USART1, you must set pin PA23 to a high level.

Note on RS485 Biasing: If communication fails, ensure the RS485 line is biased correctly. The SAM3S-EK does not populate bias resistors by default. If your RS485 master also lacks biasing, you must populate R24 and R30 on the bottom side of the evaluation kit PCB to avoid receiving incorrect characters.

To verify the MSP430 port is working correctly, connect the MSP430 hardware to a host processor via a wired serial port and use a Modbus Master software on a PC.

Run the Modbus Sample Application and attempt to read the input registers starting at protocol address 1000. The test is successful if you can read the four available registers.

Expected output format:

Polling slave (Ctrl-C to stop) ...
[1000]: 6474
[1001]: 0
[1002]: 0
[1003]: 0

To verify the port is working correctly, use a Modbus Master software to poll the slave device.

Verification Steps

1. Connect the microcontroller to your host via the serial port.
2. Run your Modbus Master software.
3. Attempt to read the input registers starting at protocol address 1000.
4. The test is successful if you can read four registers. The output should resemble the following pattern (values in registers 1001-1003 may vary, but 1000 should contain a non-zero value):

Polling slave (Ctrl-C to stop) ...
[1000]: 6474
[1001]: 0
[1002]: 0
[1003]: 0
Polling slave (Ctrl-C to stop) ...
[1000]: -8831
[1001]: 0
[1002]: 0
[1003]: 0

Once the hardware is configured and the application is running, use a MODBUS master software on a PC (connected via RS485) to verify the demo.

Verification Steps:

1. Start the MODBUS sample application.
2. Attempt to read the input registers starting at protocol address 1000.
3. The test is successful if you can read four register values. The expected output format from the master software should look like this:

Polling slave (Ctrl-C to stop) ...
[1000]: 6474
[1001]: 0
[1002]: 0
[1003]: 0