Java bindings for the SDRplay API, the driver for the SDRplay RSP1, RSP1A, RSP1B, RSP2, RSPduo, RSPdx and RSPdx-R2 software-defined radios, built on the Java Foreign Function & Memory API.
| OS | x86-64 | aarch64 |
|---|---|---|
| Linux | ✓ | ✓ |
| macOS | ✓ | ✓ |
| Windows | ✓ | ✓ |
Requires Java 23 or later, and SDRplay API 3.15 or a later 3.x version.
The jar does not contain the native library. The SDRplay API is closed source, so it cannot be built from source, and its licence does not allow it to be redistributed. It also needs a system service, which only SDRplay's installer sets up, to reach the devices. Install it from https://www.sdrplay.com/api/; jsdrplay finds theinstalled library at run time.
The jar is the same on every platform. Instead of a native build, CI checks the Java bindings on each of the six platforms against the C headers of the pinned API release; see Building.
Download jsdrplay-<version>.jar from
Releases. The rolling
nightly
pre-release tracks master.
Check that your machine can see the API and the devices:
java -jar jsdrplay-<version>.jar
jsdrplay 3.15.0, for SDRplay API 3.15 and later 3.x
SDRplay API library: /usr/local/lib/libsdrplay_api.so.3
SDRplay API version: 3.15
Devices found: 2
RSPduo, serial 1905039A32, hardware version 3
free tuners: [A, B], modes: [SINGLE_TUNER, MASTER, DUAL_TUNER]
RSP1A, serial 1712032B93, hardware version 255
try (SDRplay sdrplay = SDRplay.open();
RspDevice device = sdrplay.select(sdrplay.devices().getFirst())) {
device.setSampleRate(8_000_000);
RxChannel tuner = device.channel();
tuner.setDecimation(4, false); // 2 MHz output
tuner.setBandwidth(Bandwidth.KHZ_1536);
tuner.setFrequency(162_550_000);
tuner.setAgc(AgcMode.DISABLED);
tuner.setGain(40, 0); // gain reduction dB, LNA state
device.start(buffer -> {
float[] iq = buffer.copyInterleavedFloats(); // I, Q, I, Q, ...
queue.offer(iq);
});
Thread.sleep(10_000);
}SDRplay.open() connects to the API service and checks the API version;
sessions share one connection, which closes with the last session.
devices() lists the free devices, and select returns a subclass of
RspDevice for the model, with its extra controls: Rsp1aDevice (RSP1A and
RSP1B), Rsp2Device, RspDuoDevice, RspDxDevice (RSPdx and RSPdx-R2) or
Rsp1Device. Device settings, such as the sample rate, are on the device;
tuner settings, such as frequency and gain, are on its RxChannel.
Settings can be changed before or during streaming. While streaming, each
setter sends the change to the device. The API applies gain, frequency and
sample rate changes asynchronously and rejects a second change of the same kind
while one is in progress, so jsdrplay waits up to 250 ms for the previous one to
take effect. SampleBuffer.gainChanged(), frequencyChanged() and
sampleRateChanged() mark the first block after each change.
Samples are 16-bit I and Q, in separate arrays as the API delivers them:
copyI(), copyQ(), copyInterleaved() and copyInterleavedFloats() copy
them. buffer.i() and buffer.q() give zero-copy access, valid only on the
callback's thread until it returns; later use throws an exception rather than
reading freed memory.
SampleListener and DeviceEventListener run on the API's threads, so hand
slow work to another thread, and do not call stop() or close() from them.
An exception thrown by a listener stops delivery and is available from
listenerFailure(). Power overload events are acknowledged to the API before
they reach the listener, as the API requires. On DeviceRemoved, close the
device from another thread.
select picks single tuner mode on a free tuner, or slave mode when another
application is the master. Choose the mode with selectRspDuo:
DeviceInfo info = sdrplay.devices().stream()
.filter(d -> d.model() == RspModel.RSPDUO).findFirst().orElseThrow();
try (RspDuoDevice duo = sdrplay.selectRspDuo(info, RspDuoMode.DUAL_TUNER, Tuner.BOTH, 0)) {
duo.channel(Tuner.A).setFrequency(155_000_000);
duo.channel(Tuner.B).setFrequency(460_000_000);
duo.start(buffer -> process(buffer.tuner(), buffer.copyInterleavedFloats()));
...
}In dual tuner mode the listener is called from two threads at once, one per
tuner. Master mode takes the sample rate of both tuners, 6 or 8 MHz; another
application, or this one, can then select the free tuner as slave. Select the
master first: devices() offers slave mode only after that.
An application can select several devices, including both tuners of an RSPduo
as master and slave. The API allows one selected device per API client, so
when a device is already selected, select and selectRspDuo first start
another client with sdrplay_api_Open. The API does not count these calls, so
the last session to close still calls sdrplay_api_Close only once. jsdrplay does not expose
sdrplay_api_SwapRspDuoMode or sdrplay_api_SwapRspDuoActiveTuner: close the
device and select it again in the new mode.
Java prints a warning, which future versions will turn into an error, unless you allow native access:
java --enable-native-access=ALL-UNNAMED -cp app.jar:jsdrplay.jar my.App
On the module path, use --enable-native-access=io.github.dsheirer.sdrplay. In
your own executable jar, add Enable-Native-Access: ALL-UNNAMED to the manifest.
jsdrplay loads the SDRplay API library from, in order:
- the
jsdrplay.library.pathsystem property: the library file, or the directory containing it; nothing else is tried when it is set - where SDRplay's installer puts it:
/usr/local/libon Linux and macOS,%ProgramFiles%\SDRplay\API\x64(orARM64) on Windows, and a few distribution locations on Linux - the system library search path (
LD_LIBRARY_PATH,DYLD_LIBRARY_PATH,PATH)
SDRplay.isInstalled() reports whether it can be loaded. Without it,
SDRplay.open() throws an SDRplayException with
SDRplayError.API_NOT_FOUND and a message listing every place tried.
The API's parameter structures change between versions: 3.15 lengthened the
RSPduo tuner parameters, which moved the RSPdx fields after them. Using these
bindings with an older API would corrupt memory, so SDRplay.open() rejects
versions before 3.15 with SDRplayError.UNSUPPORTED_API_VERSION. Later 3.x
versions are accepted. Before releasing for one, move the pin (see
Releases) so that CI checks the bindings against its headers.
You need JDK 23+, plus CMake 3.16+, a C compiler and curl to run the layout check. On Windows use Git Bash and Visual Studio.
./gradlew build # jar in build/libs
./native/probe-layouts.sh # check the bindings against the headers
./gradlew test # now includes the layout check
./gradlew test -PhardwareTest=true # also test the connected devices
native/probe-layouts.sh downloads the SDRplay installer pinned in
native/versions.env, checks its SHA-256, and extracts
only the headers, without running the installer. It then:
- checks that
Native.javabinds exactly the functions insdrplay_api.h(check-bindings.sh) - compiles
layout-probe.c, which prints the size and field offsets of every API structure, and the value of every enum constant, as this platform's C compiler sees them
LayoutProbeTest then compares each of those with Layouts.java and the Java
enums. CI runs this on all six platforms. Tests that need the API run when it
is installed; the hardware tests are receive-only and never turn on a bias tee.
jsdrplay versions start with the SDRplay API version they target: jsdrplay 3.15.x is for API 3.15 and later 3.x.
| Trigger | What happens |
|---|---|
| Pull request | Checks the bindings on all six platforms and builds the jar; publishes nothing |
Merge to master |
Replaces the nightly pre-release |
| Daily schedule | Checks that the pinned installer still downloads with its checksum; rebuilds the nightly if master changed |
Tag vX.Y.Z |
Publishes a release |
To release, tag the next version on the pinned API: git tag v3.15.0 && git push origin v3.15.0. The workflow rejects a tag that does not start with the pinned
API version. For a pre-release add a suffix, such as v3.15.0-rc1.
To adopt a new API release, change SDRPLAY_API_VERSION,
SDRPLAY_INSTALLER_URL and SDRPLAY_INSTALLER_SHA256 in
native/versions.env, and SDRplay.API_VERSION, then run
native/probe-layouts.sh and the tests: they list any new function, structure
change or enum value to bring into Native.java, Layouts.java and the
enums.
Apache License 2.0. The SDRplay API is not part of jsdrplay and has its own licence: see THIRD-PARTY-NOTICES.md.