pre-release 0.1

проверка
2025-11-03 19:50:46 +03:00
parent 7e21fc7f28
commit dfadef7b43
944 changed files with 162 additions and 585750 deletions
--- a/README.md
+++ b/README.md
@@ -1,165 +1,185 @@
-# STM Modbus: подключение и использование
+# Инструкция по подключению релиза библиотеки `STM Modbus`

-Библиотека реализует Modbus RTU Slave для STM32 с использованием HAL. Работает в прерываниях с детектированием конца фрейма по IDLE линии и таймаутами через прерывание таймера.
+Данная библиотека подключается напрямую из Git, как субмодуль. Позволяя при желании обновлять её напрямую через pull.

-## Быстрый старт
-_Note: Здесь описано подключение просто архива c исходниками. Если надо подключить библиотеку как субмодуль: см. ветку release в этом репозитории._
+## Структура библиотеки

-### 1. Настройка периферии
-
- **UART**: Настройте в режиме Asynchronous, нужная скорость (9600, 19200, etc), 8N1
- **TIM**: Настройте таймер для генерации прерываний (например, 1ms tick)
- **Включите прерывания** для UART и TIM
-
-### 2. Подключение обработчиков прерываний
-
-Подключите обработчики прерываний **UART** и **TIM** в свои IRQ обработчики ***вместо*** HAL-обработчиков:
-
-```c
-#include "modbus.h"
-
-void USARTx_IRQHandler(void)
-{
-    RS_UART_Handler(&modbus1);
-    return;
-    HAL_UART_IRQHandler(&huart);
-}
-
-void TIMx_IRQHandler(void)
-{
-    RS_TIM_Handler(&modbus1);
-    return;
-    HAL_TIM_IRQHandler(&htim);
-}
+*Note: Файлы начинающиеся с `__` и которых нет в этом дереве являются **внутренними/непротестированными/недокументированными***
+```
+Modbus/
+│   inc/
+│   ├── modbus.h                # Главный заголовочный файл
+│   ├── modbus_core.h           # Базовые определения и структуры
+│   ├── modbus_coils.h          # Работа с дискретными выходами
+│   ├── modbus_holdregs.h       # Работа с регистрами хранения
+│   ├── modbus_inputregs.h      # Работа с входными регистрами
+│   ├── modbus_devid.h          # Идентификация устройства
+│   ├── rs_message.h            # Драйвер обмена по RS/UART
+├── src/
+│   ├── modbus.c                # Основная логика Modbus Slave
+│   ├── modbus_coils.c          # Реализация работы с coils
+│   ├── modbus_holdregs.c       # Реализация регистров хранения
+│   ├── modbus_inputregs.c      # Реализация входных регистров
+│   ├── modbus_devid.c          # Реализация идентификации устройства
+│   ├── modbus_data.c           # Функции доступа к данным
+│   └── rs_message.c            # Реализация драйвера RS
+├── __modbus_config.h       # Конфигурация Modbus (надо заменить)
+├── __modbus_data.h         # Структуры данных (надо заменить)
+└── __modbus_data.c         # Функции доступа (надо заменить)
 ```

-### 3. Настройка конфигурации
+## Инструкция по подключению

-В `modbus_config.h` укажите параметры устройства:
+1. **Склонируйте субмодуль** в ваш проект:

-```c
-// MODBUS PARAMS
-#define MODBUS_DEVICE_ID              1     // Адрес устройства в сети Modbus
-#define MODBUS_TIMEOUT                100   // Таймаут в тиках таймера (рекомендуется 100-200ms)
-
-// Строковые идентификаторы устройства
-#define MODBUS_VENDOR_NAME            "NIO-12"
-#define MODBUS_PRODUCT_CODE           ""
-#define MODBUS_REVISION               "Ver. 1.0"
-#define MODBUS_VENDOR_URL             ""
-#define MODBUS_PRODUCT_NAME           ""
-#define MODBUS_MODEL_NAME             "STM32F103"
-#define MODBUS_USER_APPLICATION_NAME  ""
-#define MODBUS_NUMB_OF_USEROBJECTS    0
-
-// Периферия
-#define mb_huart                      huart1  // Удобный дефайн для модбасовского UART
-#define mb_htim                       htim3   // Удобный дефайн для модбасовского таймера
+```bash
+git submodule add https://git.arktika.cyou/Razvalyaev/STM32_ExtendedLibs path/to/ExtendedLibs
+git submodule update --init --recursive
 ```

-### 4. Инициализация в коде
+2. **Скопируйте файлы конфигурации и главный include** в отдельную папку в вашем проекте (вне субмодуля) и удалите `__`:

-В `main()` после инициализации HAL:
-
-```c
-#include "modbus.h"
-
-int main(void)
-{
-    // Инициализация HAL
-    HAL_Init();
-    SystemClock_Config();
-    MX_GPIO_Init();
-    MX_USART1_UART_Init();
-    MX_TIM3_Init();
-    
-    // Инициализация Modbus
-    MODBUS_SetupHardware(&hmodbus1, &mb_huart, &mb_htim);
-    
-    // Запуск приема Modbus
-    MODBUS_SlaveStart(&hmodbus1, &MODBUS_MSG);
-    
-    while (1)
-    {
-        // Основной цикл
-    }
-}
+```
+ProjectRoot/
+├── Configs/
+│   ├── modbus_config.h          # ← скопировать из __modbus_config.h
+│   ├── modbus_data.h            # ← скопировать из __modbus_data.h
+│   └── modbus_data.c            # ← скопировать из __modbus_data.c (опционально)
+└── Modbus/						 # Субмодуль
 ```

-### 5. Настройка карты данных
+3. **Настройте конфигурацию** под ваш проект:
+	
+    3.1. Настройка периферии

-В `modbus_data.h` настройте регистры и coils под ваше устройство:
+	- **UART**: Настройте в режиме Asynchronous, нужная скорость (9600, 19200, etc), 8N1
+	- **TIM**: Настройте таймер для генерации прерываний (например, 1ms tick)
+	- **Включите прерывания** для UART и TIM

-#### Input Registers (только чтение)
-```c
-typedef struct
-{
-    uint16_t Temperature;      // Адрес 0
-    uint16_t Humidity;         // Адрес 1  
-    uint16_t Pressure;         // Адрес 2
-    uint16_t Voltage;          // Адрес 3
-} MB_DataInRegsTypeDef;
+	3.2. Подключение обработчиков прерываний

-#define R_INPUT_ADDR        0  // Начальный адрес Input регистров
-#define R_INPUT_QNT         4  // Количество Input регистров
-```
+	Подключите обработчики прерываний **UART** и **TIM** в свои IRQ обработчики ***вместо*** HAL-обработчиков:

-#### Holding Registers (чтение/запись)
-```c
-typedef struct
-{
-    uint16_t SetpointTemp;     // Адрес 0
-    uint16_t SetpointHumidity; // Адрес 1
-    uint16_t ControlMode;      // Адрес 2
-} MB_DataHoldRegsTypeDef;
+	```c
+	#include "modbus.h"

-#define R_HOLDING_ADDR      0  // Начальный адрес Holding регистров  
-#define R_HOLDING_QNT       3  // Количество Holding регистров
-```
+	void USARTx_IRQHandler(void)
+	{
+		RS_UART_Handler(&modbus1);
+		return;
+		HAL_UART_IRQHandler(&huart);
+	}

-#### Coils (1-битные)
-```c
-typedef struct
-{
-    unsigned Relay1    : 1;    // Адрес 0
-    unsigned Relay2    : 1;    // Адрес 1  
-    unsigned Pump      : 1;    // Адрес 2
-    unsigned Heater    : 1;    // Адрес 3
-    unsigned reserved  : 12;   // Резерв (выравнивание до 16 бит)
-} MB_DataCoilsTypeDef;
+	void TIMx_IRQHandler(void)
+	{
+		RS_TIM_Handler(&modbus1);
+		return;
+		HAL_TIM_IRQHandler(&htim);
+	}
+	```

-#define C_COILS_ADDR        0  // Начальный адрес Coils
-#define C_COILS_QNT         4  // Количество Coils
-```
+	3.3. В `modbus_config.h` укажите параметры устройства

-### 6. Доступ к данным в коде
+	3.4. Инициализация в коде

-```c
-// Чтение входных регистров
-uint16_t temp = MB_DATA.InRegs.Temperature;
+	В `main()` после инициализации HAL:

-// Запись в регистры хранения
-MB_DATA.HoldRegs.SetpointTemp = 2500;
+	```c
+	#include "modbus.h"

-// Управление coils
-MB_Set_Coil_Local(&MB_DATA.Coils, 0);  // Включить Relay1
-MB_Reset_Coil_Local(&MB_DATA.Coils, 1); // Выключить Relay2
+	int main(void)
+	{
+		// Инициализация HAL
+		HAL_Init();
+		SystemClock_Config();
+		MX_GPIO_Init();
+		MX_USART1_UART_Init();
+		MX_TIM3_Init();
+		
+		// Инициализация Modbus
+		MODBUS_SetupHardware(&hmodbus1, &mb_huart, &mb_htim);
+		
+		// Запуск приема Modbus
+		MODBUS_SlaveStart(&hmodbus1, &MODBUS_MSG);
+		
+		while (1)
+		{
+			// Основной цикл
+		}
+	}
+	```

-// Чтение coil
-if (MB_Read_Coil_Local(&MB_DATA.Coils, 2)) {
-    // Pump включен
-}
-```
+	3.5. Настройка карты данных

-## Поддерживаемые функции Modbus
+	В `modbus_data.h` настройте регистры и coils под ваше устройство:

-| Функция | Код | Описание |
-|---------|-----|-----------|
-| Read Coils | 0x01 | Чтение дискретных выходов |
-| Read Input Registers | 0x04 | Чтение входных регистров |
-| Read Holding Registers | 0x03 | Чтение регистров хранения |
-| Write Single Coil | 0x05 | Запись одиночного coil |
-| Write Single Register | 0x06 | Запись одиночного регистра |
-| Write Multiple Coils | 0x0F | Запись множественных coils |
-| Write Multiple Registers | 0x10 | Запись множественных регистров |
-| Read Device Identification | 0x2B | Чтение идентификации устройства |
+	**Input Registers (только чтение)**
+	```c
+	typedef struct
+	{
+		uint16_t Temperature;      // Адрес 0
+		uint16_t Humidity;         // Адрес 1  
+		uint16_t Pressure;         // Адрес 2
+		uint16_t Voltage;          // Адрес 3
+	} MB_DataInRegsTypeDef;
+
+	#define R_INPUT_ADDR        0  // Начальный адрес Input регистров
+	#define R_INPUT_QNT         4  // Количество Input регистров
+	```
+
+	**Holding Registers (чтение/запись)**
+	```c
+	typedef struct
+	{
+		uint16_t SetpointTemp;     // Адрес 0
+		uint16_t SetpointHumidity; // Адрес 1
+		uint16_t ControlMode;      // Адрес 2
+	} MB_DataHoldRegsTypeDef;
+
+	#define R_HOLDING_ADDR      0  // Начальный адрес Holding регистров  
+	#define R_HOLDING_QNT       3  // Количество Holding регистров
+	```
+
+	**Coils (1-битные)**
+	```c
+	typedef struct
+	{
+		unsigned Relay1    : 1;    // Адрес 0
+		unsigned Relay2    : 1;    // Адрес 1  
+		unsigned Pump      : 1;    // Адрес 2
+		unsigned Heater    : 1;    // Адрес 3
+		unsigned reserved  : 12;   // Резерв (выравнивание до 16 бит)
+	} MB_DataCoilsTypeDef;
+
+	#define C_COILS_ADDR        0  // Начальный адрес Coils
+	#define C_COILS_QNT         4  // Количество Coils
+	```
+
+	3.6. Доступ к данным в коде
+
+	```c
+	// Чтение входных регистров
+	uint16_t temp = MB_DATA.InRegs.Temperature;
+
+	// Запись в регистры хранения
+	MB_DATA.HoldRegs.SetpointTemp = 2500;
+
+	// Управление coils
+	MB_Set_Coil_Local(&MB_DATA.Coils, 0);  // Включить Relay1
+	MB_Reset_Coil_Local(&MB_DATA.Coils, 1); // Выключить Relay2
+
+	// Чтение coil
+	if (MB_Read_Coil_Local(&MB_DATA.Coils, 2)) {
+		// Pump включен
+	}
+	```
+
+
+
+5. **Обновление библиотеки**:
+
+После обновления субмодуля из Git, исходные файлы библиотеки будут обновлены, но ваши конфиги останутся в целевой папке и не перезапишутся:
+
+```bash
+git submodule update --remote
+```