Обновление

- Расширена документация - Доработаны ссылки. Дефолтным стал проект на GitHub - Упорядочены комменты
alexs-sh · May 20, 2019 · 65bc2f1 · 65bc2f1
1 parent d0ec1e0
commit 65bc2f1
Show file tree

Hide file tree

Showing 31 changed files with 348 additions and 326 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
-[![Total alerts](https://img.shields.io/lgtm/alerts/b/alexsteam4000/tekon-utils-pub.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/b/alexsteam4000/tekon-utils-pub/alerts/)
-[![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/b/alexsteam4000/tekon-utils-pub.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/b/alexsteam4000/tekon-utils-pub/context:cpp)
-[![codecov](https://codecov.io/bb/alexsteam4000/tekon-utils-pub/branch/master/graph/badge.svg)](https://codecov.io/bb/alexsteam4000/tekon-utils-pub)
+[![Total alerts](https://img.shields.io/lgtm/alerts/g/alexs-sh/tekon-utils.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/alexs-sh/tekon-utils/alerts/)
+[![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/alexs-sh/tekon-utils.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/alexs-sh/tekon-utils/context:cpp)
+[![codecov](https://codecov.io/gh/alexs-sh/tekon-utils/branch/master/graph/badge.svg)](https://codecov.io/gh/alexs-sh/tekon-utils)
 
 # TEKON-UTILS
 
@@ -18,6 +18,26 @@ tekon_msr -a udp:10.0.0.3:51960@9 -p'3:0xF001:0:H 3:0xF017:0:D 3:0xF018:0:T 3:0x
 9:3:0xf018:0 T 13:35:49 OK 1558082153 18000
 9:3:0x801c:2 F 38.151833 OK 1558082153 18000
 ```
+В примере выполняется чтение 4-х параметров. 
+
+Аргумент| Значение             | Описание
+--------|----------------------| ----------------------------------------------------------------------------------------------
+-a      | udp:10.0.0.3:51960@9 | чтение будет выполнено по UDP, с IP адреса - 10.0.0.3, через порт - 51960, адрес К-104 - 9
+-p      | 3:0xF001:0:H         | адрес Тэкона - 3, адрес параметра - 0xF001, индекс параметра - 0, тип параметра - H (HEX)
+
+Вывод программы: **9:3:0xf001:0 H 0x3840 OK 1558082153 18000** 
+
+Столбец | Значение             | Описание
+--------|----------------------| ----------------------------------------------------------------------------------------------
+ 1      | 9:3:0xf001:0         | адрес параметра. Адрес К-104 - 9, адрес Тэкона - 3, адрес параметра - 0xf001, индекс параметра - 0
+ 2      | H                    | тип парметра - HEX
+ 3      | 0x3840               | значение параметра
+ 4      | OK                   | качество
+ 5      | 1558082153           | метка времени (UTC)
+ 6      | 18000                | сдвиг часового пояса хоста относительно UTC
+
+Более подробную справку можно получить, запустив программу без аргументов
+или с ключем **-h**.
 
 ### Чтение архива
 ```console
@@ -27,12 +47,43 @@ tekon_arch -a udp:10.0.0.3:51960@9 -p 3:0x801C:0:12:F  -i m:12   -d 3:0xF017:0xF
 9:3:0x801c:2 F 38.151833 OK 1551380400 18000
 ...
 ```
+В примере выполняется чтение месячного архива глубиной 12 записей. 
+
+Аргумент| Значение             | Описание
+--------|----------------------| ----------------------------------------------------------------------------------------------
+-a      | udp:10.0.0.3:51960@9 | чтение будет выполнено по UDP, с IP адреса - 10.0.0.3, через порт - 51960, адрес К-104 - 9
+-p      | 3:0x801C:0:12:F      | адрес Тэкона - 3, адрес архива - 0x801C, стартовый индекс - 0, кол-во записей 12, формат -F (float)
+-m      | m:12                 | тип - m (месячный), глубина - 12
+-d      | 3:0xF017:0xF018      | адрес устройства - 3, адрес даты - 0xF017, адрес времени - 0xF018
+
+Вывод программы: **9:3:0x801c:0 F -nan OK 1546282800 18000** 
+
+Столбец | Значение             | Описание
+--------|----------------------| ----------------------------------------------------------------------------------------------
+ 1      | 9:3:0x801с:0         | адрес записи. Адрес К-104 - 9, адрес Тэкона - 3, адрес параметра - 0x801с, индекс - 0
+ 2      | F                    | тип парметра - float
+ 3      | -nan                 | значение параметра
+ 4      | OK                   | качество
+ 5      | 1546282800           | метка времени (UTC)
+ 6      | 18000                | сдвиг часового пояса хоста относительно UTC
+
+Более подробную справку можно получить, запустив программу без аргументов
+или с ключем **-h**.
 
 ### Синхронизация времени
 ```console
 tekon_sync -a udp:10.0.0.3:51960@9 -d 3:0xF017:0xF018 -p 00000001
 ```
 
+В примере выполняется запись текущего времени хоста в Тэкон. 
+
+Аргумент| Значение             | Описание
+--------|----------------------| ----------------------------------------------------------------------------------------------
+-a      | udp:10.0.0.3:51960@9 | чтение будет выполнено по UDP, с IP адреса - 10.0.0.3, через порт - 51960, адрес К-104 - 9
+-d      | 3:0xF017:0xF018      | адрес устройства - 3, адрес даты - 0xF017, адрес времени - 0xF018
+-p      | 00000001             | пароль наладчика
+
+
 ## Сборка
 
 Для сборки потребуются:
@@ -44,7 +95,7 @@ tekon_sync -a udp:10.0.0.3:51960@9 -d 3:0xF017:0xF018 -p 00000001
 ### Debian x86_64
 ```console
 apt install git cmake make gcc
-git clone  <repo>
+git clone https://github.com/alexs-sh/tekon-utils.git
 cd tekon-utils/
 mkdir build
 cd build
@@ -56,7 +107,7 @@ make test
 ### Debian ARM
 ```console
 apt install git cmake make gcc-arm-linux-gnueabihf
-git clone  <repo>
+git clone https://github.com/alexs-sh/tekon-utils.git
 cd tekon-utils/
 mkdir build-armhf
 cd build-armhf
@@ -67,7 +118,7 @@ make
 ### Windows XP x86
 ```console
 apt install git cmake make gcc-mingw-w64-i686
-git clone  <repo>
+git clone https://github.com/alexs-sh/tekon-utils.git
 cd tekon-utils/
 mkdir build-winxp-x86
 cd build-winxp-x86
@@ -77,8 +128,6 @@ make
 
 Все примеры выполнены в ОС Debian 9 x86_64.
 
-git clone  <repo> - вместо параметра <repo> следует подставить адрес репозитория, 
-например, https://github.com/alexs-sh/tekon-utils.git
 
 ## Применение
 
@@ -101,7 +150,7 @@ git clone  <repo> - вместо параметра <repo> следует под
 
 Формат вывода данных:
 
-шлюз:адрес:параметр:индекс тип значение качество UTC TZ
+*шлюз:адрес:параметр:индекс тип значение качество UTC TZ*
 ```console
 9:3:0xf001:0 H 0x3840 OK 1557900053 18000
 ```
@@ -110,7 +159,7 @@ git clone  <repo> - вместо параметра <repo> следует под
 
 Формат вывода данных:
 
-шлюз:адрес:параметр:индекс тип значение качество UTC TZ
+*шлюз:адрес:параметр:индекс тип значение качество UTC TZ*
 ```console
 9:3:0x801c:0 F -nan OK 1546282800 18000
 ```

diff --git a/tekon/message.h b/tekon/message.h
@@ -15,56 +15,56 @@ extern "C" {
 
 struct message {
 
-    // Адрес шлюза
+    /* Адрес шлюза */
     uint8_t gateway;
 
-    // Напрвяление (к / от устройства)
+    /* Напрвяление (к / от устройства) */
     enum tekon_direction dir;
 
-    // Тип сообщения
+    /* Тип сообщения */
     enum tekon_message_type type;
 
-    // Кол-во элементов. Если сообщение предпологает передачу параметров,
-    // то кол-во параметров в поле payload.parameters.
-    // Если передачу байт, то кол-во байт в payload.bytes
+    /* Кол-во элементов. Если сообщение предпологает передачу параметров,
+     * то кол-во параметров в поле payload.parameters.
+     * Если передачу байт, то кол-во байт в payload.bytes */
     uint8_t nelements;
 
-    // Данные
+    /* Данные */
     union {
         struct tekon_parameter parameters[TEKON_PROTO_ILIST_SIZE];
         uint8_t bytes[TEKON_PROTO_MAX_ADU_SIZE];
     } payload;
 
 };
 
-// Сообщение "Чтение параметра из внешнего модуля 0x11"
-// T10.96.59РД-Д1 стр. 9
-// 1 - успешно
-// 0 - ошибка
+/* Сообщение "Чтение параметра из внешнего модуля 0x11"
+ * T10.96.59РД-Д1 стр. 9
+ * 1 - успешно
+ * 0 - ошибка */
 int tekon_req_11(struct message * self, uint8_t gateway, uint8_t device, uint16_t address);
 int tekon_resp_11(struct message * self, uint8_t gateway, uint32_t value);
 
-// Сообщение "Передача во внешний модуль"
-// T10.96.59РД-Д1 стр. 9
-// 1 - успешно
-// 0 - ошибка
+/* Сообщение "Передача во внешний модуль"
+ * T10.96.59РД-Д1 стр. 9
+ * 1 - успешно
+ * 0 - ошибка */
 int tekon_req_14(struct message * self, uint8_t gateway, const void * data, size_t size);
 
-// Сообщение "Чтение интдексного параметра внешнего модуля"
-// T10.96.59РД-Д1 стр. 16
-// 1 - успешно
-// 0 - ошибка
+/* Сообщение "Чтение интдексного параметра внешнего модуля"
+ * T10.96.59РД-Д1 стр. 16
+ * 1 - успешно
+ * 0 - ошибка */
 int tekon_req_19(struct message * self, uint8_t gateway, uint8_t device, uint16_t address, uint16_t index, size_t size);
 int tekon_resp_19(struct message * self, uint8_t gateway, const uint32_t *values, size_t size);
 
-// Сообщение "Чтение списка параметров из внешних модулуй 0x1C"
-// T10.96.59РД-Д1 стр. 23
-// 1 - успешно
-// 0 - ошибка
+/* Сообщение "Чтение списка параметров из внешних модулуй 0x1C"
+ * T10.96.59РД-Д1 стр. 23
+ * 1 - успешно
+ * 0 - ошибка */
 int tekon_req_1c(struct message * self, uint8_t gateway, const uint8_t *devices, const uint16_t *addresses, const uint16_t *indexes, size_t size);
 int tekon_resp_1c(struct message * self, uint8_t gateway, const uint32_t *values, const uint8_t *quals, size_t size);
 
-// Квитанция
+/* Квитанция */
 int tekon_resp_ack(struct message * self, int positive);
 
 #ifdef __cplusplus

diff --git a/tekon/pack.c b/tekon/pack.c
@@ -18,13 +18,11 @@ struct buffer_writer {
 
 static void buffer_writer_init(struct buffer_writer * self, void * buffer, size_t size);
 
-// Запись значений в буфер.
-// 1 - успешно
-// 0 - ошибка
+/* Запись значений в буфер.
+ * 1 - успешно
+ * 0 - ошибка */
 static int buffer_writer_u8(struct buffer_writer * self, uint8_t u8);
 static int buffer_writer_u16(struct buffer_writer * self, uint16_t u16);
-//static int buffer_writer_u32(struct buffer_writer * self, uint32_t u32);
-
 
 static ssize_t pack_readem_11(void * buffer, size_t size, const struct message * message, uint8_t number);
 static ssize_t pack_readem_14(void * buffer, size_t size, const struct message * message, uint8_t number);
@@ -63,7 +61,7 @@ ssize_t tekon_req_pack(void * buffer, size_t size, const struct message * messag
 
 static ssize_t pack_readem_11(void * buffer, size_t size, const struct message * message, uint8_t number)
 {
-    // Лимиты для этого типа сообщений
+    /* Лимиты для этого типа сообщений */
     const uint8_t frame_size = 9;
     const uint8_t code = 0x11;
 
@@ -98,7 +96,7 @@ static ssize_t pack_readem_14(void * buffer, size_t size, const struct message *
     assert(message);
     assert(message->nelements > 3);
 
-    //Т10.06.59РД-Д1 стр. 10-12
+    /*Т10.06.59РД-Д1 стр. 10-12*/
     const uint8_t nelem = message->nelements;
     const uint8_t code = 0x14;
     const uint8_t command = message->payload.bytes[2];
@@ -109,13 +107,13 @@ static ssize_t pack_readem_14(void * buffer, size_t size, const struct message *
     uint8_t len = 0;
 
     switch(command) {
-    // Запись регистра
+    /* Запись регистра */
     case 0x03:
 
         frame_size = 18;
         len = 12;
         break;
-    // Установка уровня доступа
+    /* Установка уровня доступа */
     case 0x05:
         frame_size = 17;
         len =  11;
@@ -190,7 +188,7 @@ static ssize_t pack_readem_19(void * buffer, size_t size, const struct message *
 
 static ssize_t pack_readem_list_1C(void * buffer, size_t size, const struct message * message, uint8_t number)
 {
-    // Лимиты для этого типа сообщений
+    /* Лимиты для этого типа сообщений */
     const uint8_t nelem = message->nelements;
     const uint8_t frame_size = nelem * 6 + 9;
     const uint8_t len = nelem * 6 + 3;
@@ -236,11 +234,12 @@ static ssize_t pack_readem_list_1C(void * buffer, size_t size, const struct mess
 
 }
 
-// Копирование в буфер везде сделано через memcpy.
-// во-первых это устраняет проблемы с невыровненным доступом к памяти (ARMv5 например)
-// во-вторых большинство компиляторов могут правильно понять и оптимизировать
-// этот код исключив реальный вызов функции.
-// Итого, memcpy обеспечивает переносимый и очень быстрый способ записи в буфер
+/* Копирование в буфер везде сделано через memcpy.
+ * во-первых это устраняет проблемы с невыровненным доступом к памяти (ARMv5 например)
+ * во-вторых большинство компиляторов могут правильно понять и оптимизировать
+ * этот код исключив реальный вызов функции.
+ * Итого, memcpy обеспечивает переносимый и очень быстрый способ записи в буфер
+ * */
 static void buffer_writer_init(struct buffer_writer * self, void * buffer, size_t size)
 {
     assert(self);

diff --git a/tekon/pack.h b/tekon/pack.h
@@ -15,9 +15,9 @@ extern "C" {
 #include <sys/types.h>
 #include "tekon/message.h"
 
-// Записть сообщение в буфер
-// В случае успеха возврщает кол-во записанных байт
-// 0 - ошибка
+/* Записть сообщение в буфер
+ * В случае успеха возврщает кол-во записанных байт
+ * 0 - ошибка */
 ssize_t tekon_req_pack(void * buffer, size_t size, const struct message * message, uint8_t number);
 
 #ifdef __cplusplus

diff --git a/tekon/proto.h b/tekon/proto.h
@@ -14,15 +14,15 @@ extern "C" {
 #include <stddef.h>
 
 #define TEKON_INVALID_DEV_ADDR    0
-#define TEKON_INVALID_INDEX       0xFFFF // Признак невалидного индекса при четнии индексированных параметров
+#define TEKON_INVALID_INDEX       0xFFFF /* Признак невалидного индекса при четнии индексированных параметров */
 
 #define TEKON_PASSWD_LEN      8
 #define TEKON_PRIV_ADMIN      2
 #define TEKON_PRIV_USER       1
 
 #define TEKON_PROTO_MAX_ADU_SIZE    255
-#define TEKON_PROTO_PLIST_SIZE      40  // Длина списка параметров
-#define TEKON_PROTO_ILIST_SIZE      60  // Длина списка инд. параметров
+#define TEKON_PROTO_PLIST_SIZE      40  /* Длина списка параметров */
+#define TEKON_PROTO_ILIST_SIZE      60  /* Длина списка инд. параметров */
 #define TEKON_PROTO_POS_ACK         0xA2
 #define TEKON_PROTO_NEG_ACK         0xE5
 #define TEKON_PROTO_FIX_PREFIX      0x10
@@ -57,7 +57,7 @@ struct tekon_parameter {
     uint16_t address;
     uint16_t index;
     uint32_t value;
-    uint8_t qual; // значения байт качества (0 - ОК)
+    uint8_t qual; /* значения байт качества (0 - ОК) */
 };
 
 uint8_t tekon_crc(const void * buffer, size_t size);

diff --git a/tekon/test/unit_time.c b/tekon/test/unit_time.c
@@ -13,11 +13,11 @@ extern "C" {
 MU_TEST(test_month_idx_12)
 {
 
-    // контрольные значения
+    /* контрольные значения */
     mu_assert_int_eq(0x08, tekon_month_index(16, 9, 12));
     mu_assert_int_eq(0x06, tekon_month_index(17, 7, 12));
 
-    // перебор
+    /* перебор */
     size_t i;
     for(i = 0; i < 12; i++) {
         mu_assert_int_eq(i, tekon_month_index(19, i + 1, 12));