diff --git a/documents/handbook/1.LoadModules.jpg b/documents/handbook/1.LoadModules.jpg new file mode 100644 index 0000000000000000000000000000000000000000..da74df676e72f416580575f1d05e8a0bd4b06071 Binary files /dev/null and b/documents/handbook/1.LoadModules.jpg differ diff --git a/documents/handbook/2.LoadModulesOk.jpg b/documents/handbook/2.LoadModulesOk.jpg new file mode 100644 index 0000000000000000000000000000000000000000..5b98c8e0386dd626bca0449d16694b8e6f191cc0 Binary files /dev/null and b/documents/handbook/2.LoadModulesOk.jpg differ diff --git a/documents/handbook_zh_CN.md b/documents/handbook_zh_CN.md new file mode 100644 index 0000000000000000000000000000000000000000..83e268ae30f800dc7f9e21b5cb7e298d876962d3 --- /dev/null +++ b/documents/handbook_zh_CN.md @@ -0,0 +1,210 @@ +# **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", + #... + } +} +``` + 则表示没有问题。 diff --git a/documents/images/taskBus.png b/documents/images/taskBus.png new file mode 100644 index 0000000000000000000000000000000000000000..de4f69504e60289ad7b6661dd64258ffd6a75b93 Binary files /dev/null and b/documents/images/taskBus.png differ diff --git a/readme.md b/readme.md index 66e762c15312848359dcffbb3925fff8148690ce..b5b9914cd6a7f513d55166c977e57fbc36199889 100644 --- a/readme.md +++ b/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) diff --git a/taskbusplatform/images/taskBus.png b/taskbusplatform/images/taskBus.png index 38b2f13a307bafbc9d4447fe9a80fb841297714f..ffc4084483a12a97f2785adb829f04acbc3da09e 100644 Binary files a/taskbusplatform/images/taskBus.png and b/taskbusplatform/images/taskBus.png differ