1.1.8

Add docment.

README.md

@@ -32,3 +32,7 @@ SerialTool是一个实用的串口调试工具，这款工具支持串口调试
  * QScintilla: [Documentation](http://pyqt.sourceforge.net/Docs/QScintilla2), [Download](https://riverbankcomputing.com/software/qscintilla/download)
  * [QCustomPlot](http://www.qcustomplot.com/): 源码已经包含到项目中
 * 其他信息参看[readme.txt](https://github.com/Le-Seul/SerialTool/blob/master/readme.txt)文件
+
+## 文档
+
+[串口示波器协议说明](./SerialTool/doc/doc.md)

SerialTool/SerialTool.pro

@@ -47,7 +47,8 @@ SOURCES += \
     source/defaultconfig.cpp \
     source/oscopetimestamp.cpp \
     source/terminalview.cpp \
-    source/serialport.cpp
+    source/serialport.cpp \
+    source/docmentdialog.cpp
 
 HEADERS  += \
     include/aboutbox.h \
@@ -69,7 +70,8 @@ HEADERS  += \
     include/defaultconfig.h \
     include/oscopetimestamp.h \
     include/terminalview.h \
-    include/serialport.h
+    include/serialport.h \
+    include/docmentdialog.h
 
 DISTFILES += \
     resource/images/clear.png \
@@ -96,6 +98,7 @@ FORMS += \
     ui/vediobox.ui \
     ui/tcpudpport.ui \
     ui/terminalview.ui \
-    ui/serialport.ui
+    ui/serialport.ui \
+    ui/docmentdialog.ui
 
 LIBS += -lqscintilla2

SerialTool/doc/doc.md

@@ -0,0 +1,206 @@
+# 串口示波器协议
+
+## 概述
+
+为了使用串口示波器，用户需要按照SerialTool软件的协议发送数据，我们提供了
+sendwave.c以及sendwave.h这两个文件来封装这些协议，这两个文件在源码目录的
+[slave](https://github.com/Le-Seul/SerialTool/tree/master/SerialTool/slave)
+文件夹下。用户如果需要修改或者扩充协议可自行阅读源码。
+
+串口示波器分为两种传输模式：点发送模式和同步发送模式。点发送模式每个点都是独
+立发送的，而同步发送模式是将所有待发送的通道数据一起发送。因此，相比同步发送
+模式，点发送那个模式各通道之间的时间轴可能存在一些偏差，一般在±1个单位时间之
+间。但是点发送模式使用起来可能更为灵活。
+
+SerialTool还支持时间戳的发送，以方便数据分析。
+
+## 点发送模式
+
+点发送模式由以下函数来实现：
+
+``` C
+char ws_point_int8(char *buffer, char channel, int8_t value);
+char ws_point_int16(char *buffer, char channel, int16_t value);
+char ws_point_int32(char *buffer, char channel, int32_t value);
+char ws_point_float(char *buffer, char channel, float value);
+```
+
+这些函数的参数说明：
+
+* `buffer`:
+
+  > 为工作缓冲区，它最多可能需要7bytes空间。
+
+* `channle`:
+
+  > 发送的通道，取值为CH1 ~ CH16。
+
+* `value`:
+
+  > 要发送的数值，其类型由使用的函数决定（包括`int8_t`, `int16_t`, 
+    `int32_t`或者`float`）。
+
+这些函数在sendwave.c中有详细的说明。以`ws_point_int16()`为例，调用方式如下：
+``` C
+char buffer[7], len;
+int16_t value = 100; // a test value
+
+len = ws_point_int16(buffer, CH1, value);
+sendBuffer(buffer, len); // serial port send data
+```
+
+## 同步发送模式
+
+同步发送模式由以下函数实现：
+``` C
+void ws_frame_init(char *buffer);
+char ws_frame_length(const char *buffer);
+char ws_add_int8(char *buffer, char channel, int8_t value);
+char ws_add_int16(char *buffer, char channel, int16_t value);
+char ws_add_int32(char *buffer, char channel, int32_t value);
+char ws_add_float(char *buffer, char channel, float value);
+```
+
+首先要调用`ws_frame_init()`函数来初始化缓冲区。调用`ws_frame_length()`
+可以获取缓冲区占用的字节数。
+
+`ws_add_xxx()`函数用于向缓冲区中添加一个数据点，参数列表如下：
+
+* `buffer`:
+
+  > 已经初始化的帧缓冲区。
+
+* `channle`:
+
+  > 发送的通道，取值为CH1 ~ CH16。
+
+* `value`:
+
+  > 要发送的数值，其类型由使用的函数决定（包括`int8_t`, `int16_t`, 
+    `int32_t`或者`float`）。
+
+这些函数如果返回1就表示数据点添加成功，0表示添加失败（缓冲区达到最大长度）。
+
+同步发送模式的例程如下：
+``` C
+char buffer[83]; // maximum use of 83 bytes
+int value = 10000; // a test value
+
+ws_frame_init(buffer);
+ws_add_int8(buffer, CH1, (int8_t)(value / 100));
+ws_add_int16(buffer, CH2, (int16_t)(value / 20));
+ws_add_float(buffer, CH3, (float)value * 0.1f);
+sendBuffer(buffer, ws_frame_length(buffer)); // serial port send data
+```
+
+使用同步模式发送时，可以在同一帧中使用不同的数据类型，但是不建议使用重复的通道，
+因为这样可能会使缓冲区很快用完并导致时间轴错乱。
+
+## 时间戳
+
+利用时间戳，可以将下位机的时间信息发送至上位机。上位机收到时间戳并不会显示，但是
+在存储波形文件时会记录时间戳，因此时间戳可以方便地进行数据分析。
+
+下位机要发送时间戳，需要使用下列函数：
+``` C
+char ws_send_timestamp(char *buffer, ws_timestamp_t* ts);
+```
+
+`ws_timestamp_t`结构体的定义如下：
+``` C
+typedef struct {
+    uint8_t year;           // 0~99 -> 2000 ~ 2099, 7 bit
+    uint8_t month;          // month, 1 ~ 12
+    uint8_t day;            // day, 1 ~ 31
+    uint8_t hour;           // hour, 0 ~ 23
+    uint8_t min;            // minute, 0 ~ 59
+    uint8_t sec;            // second, 0 ~ 59
+    uint16_t msec;          // millisecond, 0 ~ 1000
+    uint32_t sampleRate;    // sample rate, 0 ~ 2000000
+} ws_timestamp_t;
+```
+
+发送时间戳的例程如下：
+``` C
+char buffer[10], len;
+
+len = ws_send_timestamp(buffer, &ts);
+sendBuffer(buffer, len); // serial port send data
+```
+下位机通常不需要重复发送时间戳，因为这个时间信息一般只用于记录或者辨识，相比而
+言，采样率可能在数据分析时会更有用。因此我建议下位机在以下时机发送一次时间戳：
+
+* 下位机运行之初。
+* 数据采样率发生变化之后。
+* 中断波形传输后准备再次发送波形数据前。
+
+## 完整示例代码
+
+``` C
+// include file
+#include "sendwave.h"
+
+// 串口示波器测试函数
+void plotTest(void)
+{
+    char buffer[100], len; // 缓冲区最大需要83bytes
+    static float key = 0.0f;
+    static ws_timestamp_t ts = { // 时间戳
+        17, 11, 20,      // year, month, day
+        12, 30, 45,      // hour, minute, second
+        120, 50          // msec, sample rate
+    };
+
+    // 每秒钟发送一次时间戳
+    if ((int64_t)(key * 50.0) % 100 == 0) {
+        len = ws_send_timestamp(buffer, &ts);
+        sendBuffer(buffer, len); // 串口发送数据
+    }
+
+    // 点发送模式 int8类型（8位有符号整形）
+    len = ws_point_int8(buffer, CH1, (int8_t)(sinf(key) * 64));
+    sendBuffer(buffer, len); // 串口发送数据
+
+    // 点发送模式 int16类型（16位有符号整形）
+    len = ws_point_int16(buffer, CH2, (int16_t)(sinf(key) * 4096));
+    sendBuffer(buffer, len); // 串口发送数据
+
+    // 点发送模式 int32类型（32位有符号整形）
+    len = ws_point_int32(buffer, CH3, (int32_t)(sinf(key) * 2048));
+    sendBuffer(buffer, len); // 串口发送数据
+
+    // 点发送模式 float类型（单精度浮点型）
+    len = ws_point_float(buffer, CH4, (float)(sinf(key) * 512));
+    sendBuffer(buffer, len); // 串口发送数据
+
+    // 同步模式(帧发送模式)
+    ws_frame_init(buffer);
+    ws_add_int8(buffer, CH5, (int8_t)(sinf(key) * 128));
+    ws_add_int16(buffer, CH6, (int16_t)(sinf(key) * 700));
+    ws_add_int32(buffer, CH7, (int32_t)(sinf(key) * 1024));
+    ws_add_float(buffer, CH9, (float)(sinf(key) * 256));
+    sendBuffer(buffer, ws_frame_length(buffer)); // 串口发送数据
+
+    // 更新时间计数
+    key += 0.02f;
+}
+```
+
+## 移植
+
+sendwave.c和sendwave.h中的代码在gcc和KEIL for ARM中可以编译通过，但是
+我们不能保证它可以在所有编译器下编译成功。这些代码需要标准库中包含stdint.h
+文件，如果没有这个文件，您可以使用以下代码来替换:
+``` C
+// #include <stdint.h>
+
+typedef signed char  int8_t;
+typedef signed short int16_t;
+typedef signed long  int32_t;
+```
+
+用户一般不会使用到所有的API，例如您可能不需要使用`ws_point_float()`以及
+`ws_add_float()`函数。通常，编译器不会连接未用到的函数。编译器如果会连接从未
+被调用的函数，并且要保证目标代码最少，您应当删除这些函数的源码。
+
+如果您在移植串口示波器的协议时遇到了任何问题，您也可以向作者咨询。

SerialTool/include/docmentdialog.h

@@ -0,0 +1,22 @@
+#ifndef DOCMENTDIALOG_H
+#define DOCMENTDIALOG_H
+
+#include <QDialog>
+
+namespace Ui {
+class DocmentDialog;
+}
+
+class DocmentDialog : public QDialog
+{
+    Q_OBJECT
+
+public:
+    explicit DocmentDialog(QWidget *parent = 0);
+    ~DocmentDialog();
+
+private:
+    Ui::DocmentDialog *ui;
+};
+
+#endif // DOCMENTDIALOG_H

SerialTool/include/optionsbox.h

@@ -33,7 +33,7 @@ private slots:
     void setLanguage(int index);
 
 private:
-    Ui_optionsBox ui;
+    Ui_OptionsBox ui;
     SerialTool *serialTool;
     QString fontFamily, fontStyle;
     int fontSize;

SerialTool/include/serialtool.h

@@ -1,4 +1,4 @@
-#ifndef __SERIALTOOL_H
+#ifndef __SERIALTOOL_H
 #define __SERIALTOOL_H
 
 #include <QtWidgets/QMainWindow>
@@ -47,6 +47,7 @@ private slots:
     void setOptions();
     void saveFile();
     void about();
+    void docment();
     void onVedioBoxTriggered();
     void onVedioBoxDelete();
     void currentTabChanged(int index);

SerialTool/include/terminalview.h

@@ -32,6 +32,7 @@ class TerminalView : public QWidget
     void sendDataRequest(const QByteArray &array);
 
 private:
+    void keyPressEvent(QKeyEvent  *event);
     void setSendButtonEnabled(bool status);
     void arrayToHex(QString &str, const QByteArray &arr, int countOfLine);
     void arrayToAscii(QString &str, const QByteArray &arr);

SerialTool/include/version.h

@@ -1,15 +1,15 @@
 #ifndef __VERSION_H
 #define __VERSION_H
 
-#define MAIN_VERSION      1.1.7b
+#define MAIN_VERSION      1.1.8
 
 #define SOFTWARE_NAME     "SerialTool"
 #define COPYRIGHT         "Copyleft  2017 by Wenliang"
 
 #define _STR_(s)           #s
 #define __STR(s)          _STR_(s)
 
-#define BUILD_VERSION     _STR_(3396eM)
+#define BUILD_VERSION     _STR_(374c2M)
 #define SOFTWARE_VERSION  __STR(MAIN_VERSION)
 
 #endif