中文 README | 中文快速使用手册

Start here to connect a DFONE SDR, verify all eight receive channels, and record IQ data with the Windows GUI. Instructions for building the SDK, examples, and your own application from source follow the quick-start section.

Clone or download this repository:

git clone https://github.com/MicroPhase/antsdr-dfone.git

Prepare the following items:

• A 12 V DC power supply
• A USB Type-C cable
• A Gigabit Ethernet cable

To test synchronous reception across all eight channels, also prepare:

• The supplied 1-to-8 power splitter
• Nine SMA cables
• An RF signal generator for providing the test signal

1. Connect the 12 V DC power supply to the DFONE's DC jack.
2. Connect the USB Type-C cable between the DFONE and the host computer.
3. Connect the Gigabit Ethernet cable between the DFONE and a Gigabit Ethernet port on the host computer.
4. Using eight SMA cables, connect the DFONE's eight RX ports to the eight output ports of the 1-to-8 power splitter.
5. Using the remaining SMA cable, connect the RF signal generator output to the power splitter input.

This quick start uses 192.168.1.10 as the DFONE Ethernet address. Configure the Ethernet port connected to the DFONE to use the same subnet; for example, set the host address to 192.168.1.100 with subnet mask 255.255.255.0.

The SDK's built-in default device IP is 192.168.7.2. Always use the IP address actually configured on your board.

Open Windows Command Prompt and verify connectivity:

ping 192.168.1.10

DFONE host applications use the following TCP ports:

If ping succeeds but the application cannot connect, make sure the host firewall allows TCP connections to these ports.

The precompiled test application is located in:

host_app\DFONE\user_gui\build-win-single-exe\Release

Double-click the executable to open the GUI.

Enter the DFONE's actual IP address, such as 192.168.1.10, in the device address field and click Connect. After the connection is established, the status at the top of the window displays Ready.

In the settings panel on the left, configure the baseband sample rate, RX local oscillator frequency, and RX gain for each of the eight channels.

Three capture modes are available:

• Capture calibrated IQ captures one synchronized and calibrated IQ data set.
• Capture uncorrected IQ captures one IQ data set without synchronization calibration.
• Start continuous IQ continuously captures synchronized IQ data.

For example, configure the signal generator to output a single-tone signal at 2.4 GHz, enable its RF output, and set the GUI's sample rate, RX local oscillator frequency, and gain accordingly.

Calibrated and synchronized IQ data:

Uncorrected IQ data:

The GUI can record phase-synchronized and calibrated IQ data from all eight channels, or IQ data from selected individual channels. Select a recording mode, set the desired output file size, and then click Save 8CH baseband or Start IQ Record.

The recorded IQ files are saved in the same directory as the GUI application:

The public C++ SDK library is dfone_host. It is defined by host_app/DFONE/CMakeLists.txt and exports these public headers:

#include "dfone/session.hpp"
#include "dfone/maintenance.hpp"

Install basic build tools:

sudo apt update
sudo apt install -y cmake g++

Build and install the static SDK library:

cmake -S host_app/DFONE -B host_app/DFONE/build-linux-sdk-static \
  -DCMAKE_BUILD_TYPE=Release \
  -DDFONE_BUILD_SHARED=OFF \
  -DCMAKE_INSTALL_PREFIX="$PWD/host_app/DFONE/install-linux-sdk-static"

cmake --build host_app/DFONE/build-linux-sdk-static --target install -j"$(nproc)"

Output:

host_app/DFONE/install-linux-sdk-static/include/dfone/*.hpp
host_app/DFONE/install-linux-sdk-static/lib/libdfone_host.a

Build and install the shared SDK library if your application prefers dynamic linking:

cmake -S host_app/DFONE -B host_app/DFONE/build-linux-sdk-shared \
  -DCMAKE_BUILD_TYPE=Release \
  -DDFONE_BUILD_SHARED=ON \
  -DCMAKE_INSTALL_PREFIX="$PWD/host_app/DFONE/install-linux-sdk-shared"

cmake --build host_app/DFONE/build-linux-sdk-shared --target install -j"$(nproc)"

Output:

host_app/DFONE/install-linux-sdk-shared/include/dfone/*.hpp
host_app/DFONE/install-linux-sdk-shared/lib/libdfone_host.so

The bundled examples are in host_app/DFONE/user_gui.

If you need both GUI and CLI examples, install the GUI dependencies first:

sudo apt update
sudo apt install -y cmake g++ pkg-config libglfw3-dev libglew-dev libgl1-mesa-dev

Build:

cmake -S host_app/DFONE/user_gui -B host_app/DFONE/user_gui/build \
  -DCMAKE_BUILD_TYPE=Release

cmake --build host_app/DFONE/user_gui/build -j"$(nproc)"

Executables:

host_app/DFONE/user_gui/build/dfone_user_cli
host_app/DFONE/user_gui/build/dfone_user_gui

If you only need the command-line example, the GUI dependencies are not needed:

sudo apt update
sudo apt install -y cmake g++

cmake -S host_app/DFONE/user_gui -B host_app/DFONE/user_gui/build-cli \
  -DCMAKE_BUILD_TYPE=Release \
  -DDFONE_USER_BUILD_GUI=OFF

cmake --build host_app/DFONE/user_gui/build-cli --target dfone_user_cli -j"$(nproc)"

Run:

./host_app/DFONE/user_gui/build/dfone_user_gui

Use these fields in the left panel:

1. Device IP: enter the DFONE Ethernet IP, for example 192.168.1.10.
2. Command Port: keep 49208 unless the board service was changed.
3. Data Port: keep 49209 unless the board service was changed.
4. Click Connect. The top status line should change to connected.
5. Set capture parameters, for example: Reference Clock = Default, Sample Rate MSPS = 30.72, RX LO MHz = 2400, RX Gain dB = 30, Frames = 65536.
6. Click Capture Calibrated IQ.
7. Confirm that the right panel shows capture metadata, I/Q waveforms, phase, or spectrum.

To save the returned CS16 payload on the host PC, enable Save app-side CS16, set Output Path, and capture again.

Run a calibrated IQ capture:

./host_app/DFONE/user_gui/build/dfone_user_cli capture \
  --device-ip 192.168.1.10 \
  --sample-rate 30720000 \
  --rx-lo 2400000000 \
  --rx-gain 30 \
  --frames 65536 \
  --output iq.cs16

Expected successful output includes:

capture ok
kind=calibrated
frames=65536
channel_count=8

Capture uncorrected IQ for verification or debugging:

./host_app/DFONE/user_gui/build/dfone_user_cli capture \
  --device-ip 192.168.1.10 \
  --uncorrected \
  --output iq_uncorrected.cs16

Create main.cpp:

#include "dfone/session.hpp"

#include <fstream>
#include <iostream>

int main(int argc, char **argv)
{
    const char *device_ip = argc > 1 ? argv[1] : "192.168.1.10";

    dfone::DfOneSession dev;
    if (!dev.open(device_ip)) {
        std::cerr << "open failed: " << dev.last_error() << "\n";
        return 1;
    }

    if (!dev.set_sample_rate_hz(30'720'000) ||
        !dev.set_frequency_hz(2'400'000'000ULL) ||
        !dev.set_gain_db(30)) {
        std::cerr << "configure failed: " << dev.last_error() << "\n";
        return 1;
    }

    dfone::DfOneIqCapture iq;
    if (!dev.capture_iq(65'536, iq)) {
        std::cerr << "capture failed: " << dev.last_error() << "\n";
        return 1;
    }

    std::ofstream out("my_iq.cs16", std::ios::binary);
    out.write(reinterpret_cast<const char *>(iq.payload.data()),
              static_cast<std::streamsize>(iq.payload.size()));

    std::cout << "frames=" << iq.frames
              << " channels=" << iq.channel_count
              << " bytes=" << iq.payload.size() << "\n";

    dev.close();
    return 0;
}

Create CMakeLists.txt and use the SDK source tree directly:

cmake_minimum_required(VERSION 3.16)
project(my_dfone_app LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_subdirectory(/absolute/path/to/host_app/DFONE dfone_host_build)

add_executable(my_dfone_app main.cpp)
target_link_libraries(my_dfone_app PRIVATE dfone_host)

Build and run:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"$(nproc)"
./build/my_dfone_app 192.168.1.10

If you want to link to the installed static SDK instead of using add_subdirectory, use:

cmake_minimum_required(VERSION 3.16)
project(my_dfone_app LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

set(DFONE_SDK_ROOT "/absolute/path/to/host_app/DFONE/install-linux-sdk-static")

add_executable(my_dfone_app main.cpp)
target_include_directories(my_dfone_app PRIVATE "${DFONE_SDK_ROOT}/include")
target_link_libraries(my_dfone_app PRIVATE "${DFONE_SDK_ROOT}/lib/libdfone_host.a")

For the installed shared SDK, link libdfone_host.so and make sure the shared library can be found at runtime, for example:

export LD_LIBRARY_PATH=/absolute/path/to/host_app/DFONE/install-linux-sdk-shared/lib:$LD_LIBRARY_PATH

The Windows release package contains the GUI executable:

dist\windows\DFONE-Windows-SDK-1.0.0-x64\apps\dfone_user_gui.exe

If you built only the single-executable GUI package, the output is usually:

host_app\DFONE\user_gui\dist\DFONE_User_GUI.exe

Windows GUI check:

1. Connect the DFONE Ethernet port to the PC or to the same LAN as the PC.

2. Configure the Windows Ethernet adapter to the same subnet as the board. Example: board 192.168.1.10, PC 192.168.1.100, subnet mask 255.255.255.0.

3. Open PowerShell and verify reachability:

   ping 192.168.1.10

4. Double-click dfone_user_gui.exe or DFONE_User_GUI.exe.

5. In the Device section, set: Device IP = 192.168.1.10, Command Port = 49208, Data Port = 49209.

6. Click Connect. The status line should show Connection: connected.

7. Set normal capture parameters, for example: Sample Rate MSPS = 30.72, RX LO MHz = 2400, RX Gain dB = 30, Frames = 65536.

8. Click Capture Calibrated IQ.

9. Confirm that the right panel shows Last Capture metadata and waveform, phase, or spectrum results.

If Windows Defender Firewall prompts for network access, allow access for the DFONE GUI on the network profile used by the Ethernet adapter.

The out-of-box check passes when all of the following are true:

1. The host PC can ping the DFONE Ethernet IP.
2. The GUI can enter connected state.
3. A calibrated IQ capture returns without error.
4. The returned capture reports channel_count=8.
5. Saving CS16 output creates a non-empty .cs16 file.

• ping fails: check cable, switch, subnet, duplicate IP address, and the board Ethernet IP.
• connect failed: check ports 49208 and 49209, firewall settings, and whether another program is already using the board.
• capture failed: reduce Frames, verify RF parameters, and reconnect.
• GUI does not start on Linux: install OpenGL/GLFW/GLEW packages or update the GPU driver.
• Firmware update uses TCP 49312; a disconnect after a successful update and reboot is normal.

For more API details, see API_USAGE.md, host_app/DFONE/API_USAGE.md, and host_app/DFONE/PUBLIC_API_MANUAL.md.