update Documents

documents/handbook_zh_CN.md

+# **Taskbus 使用手册**
+Taskbus 是一款基于C++/Qt的多进程软件合作平台。使用该平台，多个基于标准输入输出设备（Stdio）的进程能够互相交换数据，并共同完成较为复杂的功能。Taskbus 初衷是为不具备良好计算机编程背景的小型团队提供开发SDR软件无线电程序的能力增量，当然也可以用来做非SDR领域的任何事情。关于本软件的技术原理，请参考[taskbus_zh_CN.md](taskbus_zh_CN.md)。本手册主要介绍该软件的使用方法。
+
+[TOC]
+
+## 1. 编译
+获取可执行程序的方法主要包括源码编译和直接使用发行版。鉴于TaskBus主要使用Qt C++开发，在Linux环境下，编译比较方便，因此目前[对Windows平台准备了发行版](https://gitcode.net/coloreaglestdio/taskbus/-/releases)。如果使用发行版，则无需编译taskBus项目，因此仅需要参考1.2节配置UHD即可。本节主要介绍在windows平台下的编译和安装，Linux下因为依赖性很容易通过包管理器解决，故而不作为重点。
+
+### 1.1 获取源码
+(**直接下载发行版的用户可忽略本节**)
+从下列网址下载最新的代码：
+[https://gitcode.net/coloreaglestdio/taskbus](https://gitcode.net/coloreaglestdio/taskbus)
+也可以直接使用Git签出：
+```bash
+#for Qt5
+git clone https://gitcode.net/coloreaglestdio/taskbus.git
+#for Qt6
+git clone -b qt6 https://gitcode.net/coloreaglestdio/taskbus.git
+```
+### 1.2 安装 libUHD 并首次驱动USRP设备
+#### 1.2.1 安装libUHD库的两种方法
+** 方法（1）：直接从官网下载。 **
+从 [https://files.ettus.com/binaries/uhd/](https://files.ettus.com/binaries/uhd/) 下载新版的uhd，2022年后，一般可以安装4.x版本。
+下载安装包，直接安装后，请配置UHD的环境变量，PATH路径。配置完毕，打开CMD，运行下面的命令，以确保已经正确设置。
+```dos
+C:\>echo %UHD_PKG_PATH% [回车]
+D:\UHD4.1.0
+
+C:\>PATH [回车]
+C:\WINDOWS\system32;C:\WINDOWS;\...;D:\UHD4.1.0\bin;...;
+```
+如果不设置环境变量，编译得时候找不到头文件，运行的时候找不到libuhd.dll
+
+** 方法（2）：从Pothos SDR下载。**
+如果希望在windows下使用PothosSDR获得GNU-Radio的所有功能，可以使用软件无线电全家桶PothosSDR。从 [https://downloads.myriadrf.org/builds/PothosSDR/](https://downloads.myriadrf.org/builds/PothosSDR/) 下载最新版，直接安装。
+
+直接安装后，请配置UHD的环境变量，PATH路径。配置完毕，打开CMD，运行下面的命令，以确保已经正确设置。
+```dos
+C:\>echo %UHD_PKG_PATH% [回车]
+E:\PothosSDR
+
+C:\>PATH [回车]
+C:\WINDOWS\system32;C:\WINDOWS;\...;E:\PothosSDR\bin;...;
+```
+而后，使用脚本下载 uhd的FPGA固件。
+
+```dos
+#假设Pothos SDR 安装在 E:\，则运行
+E:\> python PothosSDR\lib\uhd\utils\uhd_images_downloader.py -i E:\PothosSDR\share\uhd [回车]
+```
+运行后，会发现uhd文件夹下多了images文件夹。
+
+#### 1.2.2 确认USRP设备运行正常
+在命令行执行：
+```dos
+C:\> uhd_usrp_probe [回车]
+```
+不报错，并显示设备的参数了，则说明安装基本正常。**请注意上述命令返回状态中的警告** ，如网卡mtu、send_buffer_size等参数的配置警告。这些警告与正确编译taskBus无关，但与发挥设备最大的吞吐能力有关。为了保证稳定持续的吞吐，需要细致的参考以下几篇文章，解决X310万兆网、千兆网、USB等各种配置。
+- [https://files.ettus.com/manual/page_transport.html](https://files.ettus.com/manual/page_transport.html)
+- [https://goldenhawking.blog.csdn.net/article/details/110727815](https://goldenhawking.blog.csdn.net/article/details/110727815)
+
+### 1.3 安装boost
+(**直接下载发行版的用户可忽略本节**)
+
+如果您已经有了boost的某个版本，可以直接使用该版本的boost。若没有安装，且仅为了编译 taskBus，则可以使用源码自带的boost.
+
+因为taskBus使用的是libUHD的C语言接口，在C++环境下，仅需要几个boost库的头文件支持。在源码的[modules/3rdlibs/boost_headers_1075.7z](../modules/3rdlibs/boost_headers_1075.7z)中，包含了boost 1.75的头文件。把该压缩包释放到libUHD或者PothosSD的include文件夹下，使得其看起来与uhd的头文件uhd.h平级。
+
+```txt
+include-|
+        |- boost
+        |- uhd
+        |...
+        |- uhd.h
+```
+
+### 1.4 检查并配置pthread
+(**直接下载发行版的用户可忽略本节**)
+pthread是一个windows下仿POSIX的线程库。pthread.h被libuhd所使用，但可能会和您编译环境中的头文件冲突。该冲突发生在使用PothosSDR和MinGW64编译器的情况下。当您使用的是Mingw64编译器，请执行以下操作：
+
+- 找到 PothosSDR\include 文件夹
+- 把pthread.h重命名为pthread.hpp
+
+### 1.5 安装Qt
+(**直接下载发行版的用户可忽略本节**)
+目前windows下请在线安装Qt，以及对应的编译器。
+
+- 由于uhd库仅仅使用了C接口，故而编译taskBus的编译器与libuhd的编译器可以是不同的。
+- 当编译器不同时，请不要使用uhd库中C接口的 C\+\+ 扩展，如试图直接从 rx_meta->rx_metadata_cpp.time_spec 使用C\+\+/boost的timestamp结构。C++在二进制上的ABI差异可能导致诡异的错误。
+
+以下编译环境是经过测试的：
+
+- MSYS2 mingw64 Qt + Pothos SDR \*
+- mingw64 Qt + Pothos SDR \*
+- MSVC2019 x64 Qt + Pothos SDR
+- MSYS2 mingw64 Qt + libUHD
+- mingw64 Qt + libUHD
+- MSVC2019 x64 Qt + libUHD
+
+（\* 表示需要进行1.4节所说的pthead替换）
+
+### 1.6 编译
+(**直接下载发行版的用户可忽略本节**)
+打开 QtCreator, 载入工程。
+- 若使用的是MSYS2环境，建议载入CMake工程。qmake工程在静态Qt库编译时，会遇到链接错误（2022-04-04测试），使用CMake可以避免错误。
+- 请参考下表选择合适的编译配置
+
+|系统|编译环境|编译器(Qt)|UHD安装方式|需配置boost头(1.3节）|需配置pthread.h（1.4节）|须留心libiio版本问题（2.2.2节）|优选项目类型|
+|--|--|--|--|--|--|--|--|
+|win|MSVC2019|MSVC2019|libUHD|Y|N|Y|qmake|
+|win|MSVC2019|MSVC2019|Pothos SDR|Y|N|N|qmake|
+|win|CMD|MinGW64|libUHD|Y|N|Y|cmake|
+|win|CMD|MinGW64|Pothos SDR|Y|Y|N|cmake|
+|win|MSYS2 bash|MinGW64|libUHD|N|N|Y|cmake|
+|win|MSYS2 bash|MinGW64|Pothos SDR|N|Y|N|cmake|
+|win|MSYS2 bash|MinGW64-static|libUHD|N|N|Y|cmake|
+|win|MSYS2 bash|MinGW64-static|Pothos SDR|N|Y|N|cmake|
+|linux|bash|gcc|apt/yum/pacman|N|N|N|cmake|
+
+如果有真实的非虚拟机linux环境，还是建议在Linux下运行。
+
+### 1.7 编译后的结果
+一旦编译完成，在输出文件夹下会产生 bin文件夹，含有所有的可执行文件。这个文件夹应该类似：
+```dos
+E:\build\bin> tree /F [回车]
+E:.
+│  subtask_warpper.exe
+│  taskBusPlatform.exe
+└─modules
+        filter_fir.exe
+        mod_fm.exe
+        mod_fm_dem.exe
+        network_p2p.exe
+        resample_pqfraction.exe
+        sink_file.exe
+        sink_plots.exe
+        sink_plutosdr.exe
+        sink_soundcard.exe
+        sink_SQL.exe
+        source_file.exe
+        source_plutosdr.exe
+        source_soundcard.exe
+        transform_fft.exe
+        uhd_usrp_continous.exe
+        uhd_usrp_io.exe
+        warpper_scripts.exe
+        warpper_stdio.exe
+```
+
+## 2 安装
+taskBus由若干可执行文件（在windows下就是exe文件）共同完成任务。为脱离编译器环境运行，这些模块所需要的动态链接库都需要位于可发现的位置上。对Linux而言，由于使用的都是官方库，所以不存在安装问题。基本上双击 taskBusPlatform 就能启动。对Windows而言，需要格外注意依赖项。建议下载[https://dependencywalker.com/](https://dependencywalker.com/)以便在出问题时查看依赖。
+
+### 2.1 执行Qt发布
+
+打开Qt的命令行，在bin文件夹下，执行Qt发布工具。如果是静态链接，则无需本步骤。
+
+```dos
+E:\build\bin> windeployqt  --compiler-runtime taskBusPlatform.exe
+E:\build\bin> windeployqt  --compiler-runtime --dir . modules/sink_sql.exe
+E:\build\bin> windeployqt  --compiler-runtime --dir . modules/sink_soundcard.exe
+E:\build\bin> windeployqt  --compiler-runtime modules/sink_sql.exe
+E:\build\bin> windeployqt  --compiler-runtime modules/sink_soundcard.exe
+```
+
+### 2.2 确认额外的动态库
+
+即使是静态链接到Qt，还是需要动态库的支持。
+#### 2.2.1 fftw
+在bin文件夹执行命令:
+```dos
+E:\build\bin> modules\transform_fft.exe
+```
+若报错，说明需要拷贝源码文件夹 taskbus\modules\3rdlibs\win32\fftw\x64\libfftw3-3.dll 到bin\modules文件夹下。
+
+#### 2.2.2 解决libiio::libusb冲突
+若使用Pluto SDR，请确保libiio不要使用旧版进行安装。旧版会在windows\system32下释放libusb-1.0.dll，与uhd的libusb-1.0.dll冲突。
+解决方法：
+- 把libiio的文件夹 （如taskbus\modules\3rdlibs\win32\libiio\MS64）中所有文件拷贝到一个单独的文件夹下，并把source_plutosdr,sink_plutosdr两个模块移动到本文件夹。
+- 直接使用Pothos SDR全家桶，不安装libiio
+
+#### 2.2.3 MSYS64环境额外处理
+MSYS64环境依赖的开源库，请在msys64 bash下使用ldd查找缺项。
+```bash
+$ ldd transform_fft.exe | grep "mingw64"
+        libgcc_s_seh-1.dll => /mingw64/bin/libgcc_s_seh-1.dll (0x7ffd1e7f0000)
+        libwinpthread-1.dll => /mingw64/bin/libwinpthread-1.dll (0x7ffd1e110000)
+        //...
+```
+
+### 2.3 加载所有的模块
+打开 taskBusPlatform.exe, 点击“载入模块”，定位到modules文件夹，全选除了warpper_scripts.exe之外的文件，可以看到加载的结果。如果如下图所示，表示加载成功。
+![LoadModules](handbook/1.LoadModules.jpg)
+![LoadModules](handbook/2.LoadModulesOk.jpg)
+
+### 2.4 排查问题
+如果发现缺少某个模块，请到命令行下，执行 模块名.exe --information,若能够输出json，则表示正常。否则，请对照出错提示，结合[dependencywalker](https://dependencywalker.com/)或者ldd查看依赖。
+比如，对fft模块，执行:
+```dos
+E:\build\bin> modules\transform_fft.exe --information [回车]
+{
+        "transform_fft":{
+                "name":"libfftw",
+                "parameters":{
+                         "sptype":{
+                                "type":"enum",
+ #...
+        }
+}
+```
+ 则表示没有问题。

readme.md

@@ -19,9 +19,11 @@ Taskbus 从感官上提供一种类似Simulink或GNU-Radio的模块化拖拽界
 
 Taskbus provides a modular drag-and-drop interface like Simulink or gnu-radio that can be used to implement (quasi-)real-time processing logic on a general-purpose computer. However, structurally, it is completely different from the two. It provides a process management platform by defining a feature release and data exchange standard to combine processes developed in different languages.
 
-![Project Demo](documents/images/main_ui_en.png)
+![Project Demo](documents/images/taskBus.png)
 
-[更多信息参看说明（简体中文）](./documents/taskbus_zh_CN.md)
+[更多技术背景参看说明（简体中文）](./documents/taskbus_zh_CN.md)
+
+[更多使用说明参看手册（简体中文）](./documents/handbook_zh_CN.md)
 
 [For detailed information, please follow this link.(Eng)](./documents/taskbus_en.md)