Adjusting Stream Rate - Developer Docs

Overview

The glove’s six data streams push at around 130 Hz by default. Most applications can’t use that much, and Subscription.set_rate(hz) lowers the rate at the device itself, saving bandwidth and CPU compared with decimating frames in your application. One hard requirement: the device firmware must support rate control. The Wuji Glove needs v0.11.4 or later, and the Wuji Hand 2 needs v2.3.0 or later. The glove used here runs firmware 0.11.2, so what this page documents in full is the behavior when that requirement isn’t met, with the success path described from the API contract. Matching examples: examples/python/wuji_glove/6.set_stream_rate.py and examples/c/wuji_glove/1_set_stream_rate.c. For the list of adjustable streams and their API definitions, see Hand Tracking. This page covers only how to run it and what the measurements show.

The success path on this page isn’t verified on hardware, because the available device’s firmware doesn’t meet the requirement. The failure paths, evaluation order, parameter bounds, and the difference in behavior between the two bindings are all measured.

Prerequisites

Hardware

Item	Requirement
Wuji Glove	1, firmware v0.11.4 or later
Connection	Ethernet

Check the firmware version:

print(glove.version().get())

Software

Item	Requirement
Operating system	Ubuntu 22.04 LTS or later
Wuji SDK	v2026.8.31 or later
Python	3.10 or later
C toolchain	CMake 3.16 or later, plus the extracted SDK package

Python
C

pip install wuji-sdk

cmake -S examples/c/wuji_glove -B build/glove \
  -DWUJI_SDK_INCLUDE_DIR="${SDK}/include" \
  -DWUJI_SDK_LIB="${SDK}/lib/libwuji_sdk_c.so"
cmake --build build/glove --target 1_set_stream_rate

Before You Start

Read Subscribing With Callbacks first. set_rate is a method on a subscription handle, so a subscription is required before calling it.

Which Streams Are Adjustable

Category	Streams	`set_rate`
Rate entry points	`emf_poses`, `tactile`, `tactile_zones`, `imu_raw/{palm,thumb,index,middle,ring,pinky}`	Supported
Derived streams	`hand_joint_angles`, `hand_skeleton`, `tip_poses`, `imu_data/*`, `tactile_point_cloud`	Rejected, they follow their source
Global streams	`tf`, `tf_static`	Not supported

Lowering a source stream lowers every stream derived from it. Drop emf_poses to 30 Hz and hand_joint_angles, hand_skeleton, and tip_poses all follow, sparing you a proportional share of the solver cost.

Stream Rate Scope

This is the most commonly misread part of set_rate:

The setting applies to every subscriber of that stream, including other processes, Wuji Studio, and recorders
When the last subscription to that stream closes, the rate returns to the device default
A device reconnect resets it as well

So keeping a lower rate in effect means holding that subscription handle open. The example says as much in a comment: Keep the handle open for as long as you want its rate to stay in effect. When several clients share a device, the rate you lower is one everyone feels. Coordinate before changing it in a shared setup.

Data Flow

The checks run in order, and that order decides which error you see.

Failure Paths

The device runs firmware 0.11.2, below the required v0.11.4.

Rate Entry Streams Stop at the Firmware Gate

WujiException: Unsupported operation: device 'WG1KA00XXXXXXXXX' runs firmware without rate control

emf_poses, tactile, and tactile_zones all report the same thing. Passing 0 to restore the default hits the same wall, because the firmware gate comes before the parameter.

Derived Streams Stop at the Entry-Point Check, Regardless of Firmware

WujiException: Unsupported operation: 'hand_joint_angles' is not a rate-control entry point
WujiException: Unsupported operation: 'hand_skeleton' is not a rate-control entry point
WujiException: Unsupported operation: 'tactile_point_cloud' is not a rate-control entry point

This check runs before the firmware gate, so newer firmware reports exactly the same error. Seeing this means changing which stream you call, not upgrading firmware.

Global Streams Report an Internal Error

WujiException: Internal error: Device '' not registered

Both tf and tf_static report this. It isn’t a friendly message, so recognize it as “I called set_rate on a global stream.” Global streams don’t support rate control at all, since they aggregate across devices and no single device can receive the command.

Parameter Range: uint16

The C signature reads:

WujiStatus wuji_sub_set_rate(struct WujiSub *sub, uint16_t frequency_hz,
                             uint16_t *out_actual_hz);

Python uses the same 16-bit unsigned type. Measured bounds:

Input	Result
`-1`	`OverflowError: out of range integral type conversion attempted`
`65535`	Reaches the firmware gate, so the parameter is valid
`65536`	`OverflowError`

Negatives and anything above 65535 are stopped in the binding layer and never reach the device.

The Two Bindings Handle Errors Differently

Given the same firmware-gate error, the two examples react in opposite ways:

	Behavior	Consequence
Python example	`set_rate` raises `WujiException` with no try	The program crashes out, receiving no frames at all
C example	Checks the return code, prints the error, and continues	The subscription keeps working and collects its full 2 seconds

Measured output from the C example:

wuji_sub_set_rate failed: Unsupported operation: device 'WG1KA00XXXXXXXXX' runs firmware without rate control
emf_poses frame: 5 poses
emf_poses frame: 5 poses
emf_poses frame: 5 poses
...

The C approach is the sturdier one. Rate control is an optional optimization and shouldn’t take down a capture pipeline because a device runs older firmware. When adapting the Python example, wrap set_rate in a try:

try:
    actual = sub.set_rate(30)
    print(f"lowered to {actual} Hz")
except WujiException as e:
    print(f"rate control unavailable, running at the default rate: {e}")

Runtime Handling

Branch point	Behavior	What to do
Firmware below v0.11.4	`runs firmware without rate control`	Upgrade the firmware, or catch the exception and run at the default rate
Called on a derived stream	`is not a rate-control entry point`	Call its source stream instead, and derived streams follow
Called on a global stream	`Internal error: Device '' not registered`	Global streams don’t support rate control
Negative or above 65535	`OverflowError`	The parameter is a uint16
Device doesn’t support the requested rate	Returns the quantized value it applied	Use the return value, don’t assume it equals the request
Last subscription to the stream closes	The rate returns to the device default	Hold the handle to keep the lower rate
Device reconnects	The rate resets	Call it again after reconnecting
Another client subscribes to the same stream	It gets the lowered rate too	Coordinate before changing rates on a shared device

The older emf_poses_rate_divider API (Python glove.emf_poses_rate_divider(), C wuji_glove_get/set_emf_poses_rate_divider) has been removed. Upgrade to firmware v0.11.4 or later and use set_rate on an emf_poses subscription. One practical difference: the old divider persisted across reconnects, while set_rate doesn’t.

Integration Steps

Python
C

import asyncio
from wuji_sdk import SdkManager, DeviceType, WujiException

REQUESTED_HZ = 30

async def main():
    manager = SdkManager.instance()

    # 1. Discover and connect
    devices = [d for d in manager.scan() if d.device_type == DeviceType.WujiGlove]
    glove = manager.connect(sn=devices[0].sn, device_name="glove")
    print(f"Firmware version: {glove.version().get()}")

    # 2. Subscribe first. set_rate is a method on the subscription handle,
    #    and closing that handle resets the rate
    sub = glove.emf_poses().subscribe()

    # 3. Lower the rate. Older firmware raises, so wrap it and keep going
    try:
        actual = sub.set_rate(REQUESTED_HZ)
        # The device may quantize to a rate it supports. Use the return value
        print(f"requested {REQUESTED_HZ} Hz, device applied {actual} Hz")
    except WujiException as e:
        print(f"rate control unavailable, running at the default rate: {e}")

    # 4. Read frames as usual. Derived streams already follow the new rate
    for _ in range(5):
        frame = await sub.recv_async()
        print(f"{len(frame.poses)} poses")

    # 5. Pass 0 to restore the device default
    try:
        print(f"restored to the device default: {sub.set_rate(0)} Hz")
    except WujiException:
        pass

    # 6. Close the handle. The rate resets at this moment too
    sub.close()
    manager.disconnect_all()

asyncio.run(main())

#include "wuji_sdk.h"

#define REQUESTED_HZ 30

/* 1. Initialize, discover, connect. See the callback subscription page */

/* 2. Subscribe first */
struct WujiSub *sub = NULL;
if (wuji_glove_subscribe_emf_poses(dev, on_emf_poses, &ctx, &sub) != WUJI_STATUS_OK) {
    fprintf(stderr, "subscribe failed: %s\n", wuji_last_error());
    return 1;
}

/* 3. Lower the rate. Check the return code without aborting what follows */
uint16_t actual = 0;
WujiStatus st = wuji_sub_set_rate(sub, REQUESTED_HZ, &actual);
if (st != WUJI_STATUS_OK) {
    /* Streams without rate control return WUJI_STATUS_ERR_UNSUPPORTED (-8)
     * and send no rate-control request to the device */
    fprintf(stderr, "wuji_sub_set_rate failed: %s\n", wuji_last_error());
} else {
    printf("requested %d Hz, device applied %u Hz\n", REQUESTED_HZ, actual);
}

/* 4. Receive frames as usual, with callbacks on SDK worker threads */
sleep(2);

/* 5. Pass 0 to restore the device default */
uint16_t restored = 0;
if (wuji_sub_set_rate(sub, 0, &restored) == WUJI_STATUS_OK) {
    printf("restored to the device default: %u Hz\n", restored);
}

/* 6. Close the handle. The rate resets at this moment too */
wuji_sub_close(sub);
wuji_dev_disconnect(dev);
wuji_dev_release(dev);
wuji_shutdown();

Subscribe before calling set_rate. Without an active subscription, the active-subscription gate rejects the call.

Running It

Python
C

python examples/python/wuji_glove/6.set_stream_rate.py

./build/glove/1_set_stream_rate

Python output on firmware 0.11.2, where the program stops at set_rate:

Connected: WG1KA00XXXXXXXXX
Traceback (most recent call last):
  ...
  File "6.set_stream_rate.py", line 43, in main
    actual = sub.set_rate(REQUESTED_HZ)
wuji_sdk.WujiException: Unsupported operation: device 'WG1KA00XXXXXXXXX' runs firmware without rate control

C output on the same device, which keeps receiving frames after the error:

  SN=WG1KA00XXXXXXXXX  Type=WujiGlove  Address=192.168.1.100:50001
wuji_sub_set_rate failed: Unsupported operation: device 'WG1KA00XXXXXXXXX' runs firmware without rate control
emf_poses frame: 5 poses
emf_poses frame: 5 poses
...

Measured on a right-hand Wuji Glove running firmware 0.11.2. With firmware that meets the requirement, Python output looks like this:

Connected: <serial number>
emf_poses: requested 30 Hz, device applied 30 Hz
emf_poses frame at 30 Hz: 5 poses
...
restored to the device default: 0 Hz

device applied may differ from the request, because the device quantizes to a rate it supports.

Adapting It

Use the Return Value, Not the Request

set_rate returns the rate the device actually applied. Sizing timeouts, buffers, or sampling windows from the requested value goes wrong as soon as quantization kicks in.

How Much Lowering the Rate Saves

It scales linearly. From 130 Hz to 30 Hz, both network traffic and callback count fall to about 23%. Recording benefits most directly: all eight streams with zstd measured about 72 MB per minute, which becomes roughly 17 MB per minute at 30 Hz. Lowering emf_poses also saves hand-solver CPU, because derived streams follow.

Lowering the Rate Doesn’t Change Queue Capacity

The subscription queue still holds 1024 frames. At a lower rate those same 1024 frames cover a longer window, so a slow consumer actually gains headroom. See Subscribing Asynchronously.

Keeping a Low Rate Without Holding a Handle

There’s no mechanism that persists across connections today. The old emf_poses_rate_divider had that property and has been removed. The current approach is to hold the subscription handle inside your long-running service.

Subscribing With Callbacks: measured rates for all six streams
Subscribing Asynchronously: the subscription queue’s 1024-frame boundary
Recording Data: how lowering the rate affects file size
Wuji Hand 2 Adjusting Stream Rate: the same API on the dexterous hand
Data Subscription: subscription model and lifecycle

​Overview

​Prerequisites

​Hardware

​Software

​Before You Start

​Which Streams Are Adjustable

​Stream Rate Scope

​Data Flow

​Failure Paths

​Rate Entry Streams Stop at the Firmware Gate

​Derived Streams Stop at the Entry-Point Check, Regardless of Firmware

​Global Streams Report an Internal Error

​Parameter Range: uint16

​The Two Bindings Handle Errors Differently

​Runtime Handling

​Integration Steps

​Running It

​Adapting It

​Use the Return Value, Not the Request

​How Much Lowering the Rate Saves

​Lowering the Rate Doesn’t Change Queue Capacity

​Keeping a Low Rate Without Holding a Handle

​Related

Overview

Prerequisites

Hardware

Software

Before You Start

Which Streams Are Adjustable

Stream Rate Scope

Data Flow

Failure Paths

Rate Entry Streams Stop at the Firmware Gate

Derived Streams Stop at the Entry-Point Check, Regardless of Firmware

Global Streams Report an Internal Error

Parameter Range: uint16

The Two Bindings Handle Errors Differently

Runtime Handling

Integration Steps

Running It

Adapting It

Use the Return Value, Not the Request

How Much Lowering the Rate Saves

Lowering the Rate Doesn’t Change Queue Capacity

Keeping a Low Rate Without Holding a Handle

Related