MacKwnoX/NX2navi
1
0
Fork 0
mirror of https://github.com/tangerineturtle1/NX2navi.git synced 2026-11-15 19:19:58 -04:00
Code Issues Packages Projects Releases Wiki Activity

Add the encoding and the report schedule for HD rumble on Switch controllers, with their check.

Browse Source 
runtime/rumble_hd.c turns one of the game's vibration values (a low and a high band, each with a frequency and an
amplitude) into the four bytes a linear actuator's rumble report takes, clamps the frequencies to each band's ends and
the amplitude to the last safe step, and decides when a report is written: the newest value only, a held one again
every 30 ms, the neutral value three times once the game stops. Nothing calls it yet.

tests/rumble_hd_check.py builds it alone, checks known values, the clamps and a batch reduced to its reports, and
decodes a sweep of values with formulae of its own.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
chrg6
2026-11-12 22:27:15 -05:00
parent a79b0a5125
commit 59e3c6c35a
5 changed files with 535 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/building.md
View File

@@ -529,6 +529,14 @@ files.
A change to how a gamepad's axes are read (`runtime/input.c` `pad_axis`: an axis counts once it has been seen at rest)
passes `python tests\pad_rest_check.py`, which builds that function with stand-ins for SDL. No game files.
A change to HD rumble's encoding or report schedule (`runtime/rumble_hd.c`: a vibration value as the bytes of a Switch
controller's rumble report, and which reports are written when) passes `python tests\rumble_hd_check.py`, which builds
that file alone: known values and the neutral one, the frequency and amplitude clamps (no amplitude step above the
actuators' safe maximum), a report's data for two actuators and for one, and a batch of values reduced to the reports
written (the newest value at once, a held one again every 30 ms, the neutral value three times once the game stops).
The script then decodes a sweep of encoded values with formulae of its own. No game files, no SDL, no controller: what
a controller does with the reports is not covered.
A change to how a mesh pipeline's fragment module gets the inputs no mesh output feeds (`runtime/vk_pipeline.c`
`spirv_mesh_outputs`, `spirv_fs_fill_inputs`) passes `python tests\fs_fill_inputs_check.py`, which builds both
functions and runs them on mesh and fragment shaders it compiles with glslang, then validates the result. No game

133
runtime/rumble_hd.c Normal file
View File

@@ -0,0 +1,133 @@
// HD rumble for controllers with linear actuators: the encoding of a vibration value and the report schedule
// (rumble_hd.h). The byte layout and the step tables are those of the Switch controllers' rumble output report.
//
// One actuator's value is four bytes, for a high band (hf, 9 bits; its amplitude ha, 7 bits) and a low band (lf,
// 7 bits; its amplitude la, 7 bits):
// byte 0 hf bits 0-7
// byte 1 hf bit 8 in bit 0, ha in bits 1-7
// byte 2 lf in bits 0-6, la bit 0 in bit 7
// byte 3 0x40 + la bits 1-6
// Frequencies are steps of 1/32 octave above 10 Hz: n = round(32 * log2(f / 10)). The low band takes n 0x41..0xBF
// (40.9 to 626.3 Hz) as lf = n - 0x40, the high band n 0x61..0xDF (81.8 to 1252.6 Hz) as hf = (n - 0x60) * 4.
// Amplitudes are steps 0..100 on a scale that is finer where the amplitude is larger (rumble_hd_step_amp), written to
// both bands as ha = la = step. Steps above 100 exist in the format and drive the actuator past what it is built for;
// rumble_hd_amp_step never returns one.
#include <math.h>
#include <string.h>
#include "rumble_hd.h"
const uint8_t rumble_hd_neutral[RUMBLE_HD_DATA] = {0x00, 0x01, 0x40, 0x40, 0x00, 0x01, 0x40, 0x40};
// The amplitude scale: step 0 is off, step 1 the smallest amplitude there is, steps 2 to 15 a quarter octave apart,
// 16 to 31 a sixteenth, 32 to 100 a thirty-second, ending at 1.0.
#define AMP_STEP1 0.007843f
#define AMP_STEP2 0.011823f
float rumble_hd_step_amp(int step) {
if (step <= 0) return 0;
if (step == 1) return AMP_STEP1;
if (step < 16) return AMP_STEP2 * powf(2, (float)(step - 2) / 4);
if (step < 32) return powf(2, (float)step / 16) / 17;
if (step > RUMBLE_HD_AMP_STEPS) step = RUMBLE_HD_AMP_STEPS;
return powf(2, (float)step / 32) / 8.7f;
}
static int clampi(int v, int lo, int hi) { return v < lo ? lo : v > hi ? hi : v; }
int rumble_hd_amp_step(float a) {
if (!(a >= AMP_STEP1 / 2)) return 0; // also a NaN
if (a >= 1) return RUMBLE_HD_AMP_STEPS;
// The three ranges meet half way (on the log scale) between their neighbouring steps: 1 and 2, 15 and 16, 31 and 32.
if (a < 0.00963f) return 1;
if (a < 0.1150f) return clampi(2 + (int)lroundf(4 * log2f(a / AMP_STEP2)), 2, 15);
if (a < 0.2276f) return clampi((int)lroundf(16 * log2f(a * 17)), 16, 31);
return clampi((int)lroundf(32 * log2f(a * 8.7f)), 32, RUMBLE_HD_AMP_STEPS);
}
// The frequency step of f Hz within lo..hi (step numbers); a NaN or a frequency at or below 0 is the lowest.
static int freq_step(float f, int lo, int hi) {
if (!(f > 0)) return lo;
float n = 32 * log2f(f / 10);
return n <= (float)lo ? lo : n >= (float)hi ? hi : clampi((int)lroundf(n), lo, hi);
}
void rumble_hd_encode(const RumbleHdValue *v, float strength, uint8_t out[RUMBLE_HD_SIDE]) {
float s = strength > 0 ? strength : 0;
int la = rumble_hd_amp_step(v->amp_low * s), ha = rumble_hd_amp_step(v->amp_high * s);
if (!la && !ha) { memcpy(out, rumble_hd_neutral, RUMBLE_HD_SIDE); return; }
int lf = freq_step(v->freq_low, 0x41, 0xBF) - 0x40, hf = (freq_step(v->freq_high, 0x61, 0xDF) - 0x60) * 4;
out[0] = (uint8_t)(hf & 0xff);
out[1] = (uint8_t)((hf >> 8) | ha << 1);
out[2] = (uint8_t)(lf | (la & 1) << 7);
out[3] = (uint8_t)(0x40 + (la >> 1));
}
void rumble_hd_data(const RumbleHdValue v[2], const int live[2], float strength, int one, uint8_t out[RUMBLE_HD_DATA]) {
memcpy(out, rumble_hd_neutral, RUMBLE_HD_DATA);
float power[2] = {0, 0};
for (int s = 0; s < 2; s++) {
if (!live[s]) continue;
rumble_hd_encode(&v[s], strength, out + s * RUMBLE_HD_SIDE);
// how strong the side is, for a controller that can play only one: the two bands' amplitudes as energy
float al = v[s].amp_low > 0 ? v[s].amp_low : 0, ah = v[s].amp_high > 0 ? v[s].amp_high : 0;
power[s] = al * al + ah * ah;
}
if (!one) return;
int pick = power[1] > power[0];
memcpy(out + (1 - pick) * RUMBLE_HD_SIDE, out + pick * RUMBLE_HD_SIDE, RUMBLE_HD_SIDE);
}
void rumble_hd_report(const uint8_t data[RUMBLE_HD_DATA], unsigned number, uint8_t *out, unsigned n) {
memset(out, 0, n);
out[0] = RUMBLE_HD_REPORT_ID;
out[1] = (uint8_t)(number & 0xf);
memcpy(out + 2, data, RUMBLE_HD_DATA);
}
static int is_neutral(const uint8_t d[RUMBLE_HD_DATA]) { return !memcmp(d, rumble_hd_neutral, RUMBLE_HD_DATA); }
// What the controller is to play at `now`: the game's data while it is fresh and the path is on, else the neutral value.
static const uint8_t *target(const RumbleHd *h, int on, uint64_t now) {
return on && h->have && now - h->want_at <= RUMBLE_HD_STALE_NS ? h->want : rumble_hd_neutral;
}
void rumble_hd_post(RumbleHd *h, const uint8_t data[RUMBLE_HD_DATA], uint64_t now) {
memcpy(h->want, data, RUMBLE_HD_DATA);
h->want_at = now;
h->have = 1;
}
int rumble_hd_due(const RumbleHd *h, int on, uint64_t now, uint64_t gap_ns, uint8_t out[RUMBLE_HD_DATA]) {
const uint8_t *t = target(h, on, now);
int due;
if (!h->any) due = !is_neutral(t); // a controller that got nothing yet is at rest already
else if (memcmp(t, h->sent, RUMBLE_HD_DATA)) due = now - h->sent_at >= gap_ns;
else if (is_neutral(t)) due = h->neutral_left > 0 && now - h->sent_at >= gap_ns;
else due = now - h->sent_at >= RUMBLE_HD_REFRESH_NS;
if (due) memcpy(out, t, RUMBLE_HD_DATA);
return due;
}
void rumble_hd_sent(RumbleHd *h, const uint8_t data[RUMBLE_HD_DATA], uint64_t now) {
if (!is_neutral(data)) h->neutral_left = 0;
else if (!h->any || !is_neutral(h->sent)) h->neutral_left = RUMBLE_HD_NEUTRAL_REPORTS - 1;
else if (h->neutral_left > 0) h->neutral_left--;
memcpy(h->sent, data, RUMBLE_HD_DATA);
h->sent_at = now;
h->any = 1;
}
int rumble_hd_idle(const RumbleHd *h, int on, uint64_t now) {
if (!is_neutral(target(h, on, now))) return 0;
return !h->any || (is_neutral(h->sent) && h->neutral_left == 0);
}
int rumble_hd_buzzing(const RumbleHd *h) { return h->any && !is_neutral(h->sent); }
void rumble_hd_forget(RumbleHd *h) {
h->any = 0;
h->neutral_left = 0;
h->sent_at = 0;
memset(h->sent, 0, sizeof h->sent);
}

75
runtime/rumble_hd.h Normal file
View File

@@ -0,0 +1,75 @@
// HD rumble: the game's vibration values for a controller with linear actuators (Switch Pro Controller, Joy-Con), as
// the bytes of the controller's rumble output report, and the decision when a report is written. Such an actuator takes
// a frequency and an amplitude for a low and a high band, which is what the game sends (ov_input.c VibrationValue), so
// nothing is reduced to motor strengths here. Pure: no SDL and no platform calls; input.c (hd_tick) writes what this
// file decides. Checked by tests/rumble_hd_check.py.
#pragma once
#include <stdint.h>
// One actuator's value as the game sends it: amplitudes 0..1, frequencies in Hz.
typedef struct { float amp_low, freq_low, amp_high, freq_high; } RumbleHdValue;
enum {
RUMBLE_HD_SIDE = 4, // bytes of one actuator's value in a report
RUMBLE_HD_DATA = 8, // ... and of a report's two: the left actuator's, then the right one's
RUMBLE_HD_REPORT_ID = 0x10, // the output report that carries nothing but rumble data
RUMBLE_HD_REPORT = 10, // its bytes that count: the id, the report's number, the data
RUMBLE_HD_AMP_STEPS = 100, // the highest amplitude step written (amplitude 1.0): the steps above it overdrive the actuator
RUMBLE_HD_NEUTRAL_REPORTS = 3, // how many times in a row the neutral value is written when the vibration ends
};
// The frequencies an actuator takes: the low band's and the high band's ends, in Hz. Others are clamped to them.
#define RUMBLE_HD_LOW_MIN 40.875885f
#define RUMBLE_HD_LOW_MAX 626.286133f
#define RUMBLE_HD_HIGH_MIN 81.75177f
#define RUMBLE_HD_HIGH_MAX 1252.572266f
#define RUMBLE_HD_STALE_NS 250000000ull // values the game has not renewed for this long count as neutral
#define RUMBLE_HD_REFRESH_NS 30000000ull // a value that still holds is written again this often
#define RUMBLE_HD_GAP_NS 15000000ull // the default time between two reports (rumble_hd_due's gap)
// The value of an actuator at rest (no amplitude, 160 Hz and 320 Hz), twice.
extern const uint8_t rumble_hd_neutral[RUMBLE_HD_DATA];
// The amplitude step (0..RUMBLE_HD_AMP_STEPS) nearest to a, and that step's amplitude. A NaN or a value below half of
// the first step is step 0; 1 and everything above it is the last step.
int rumble_hd_amp_step(float a);
float rumble_hd_step_amp(int step);
// One actuator's value as its four report bytes. strength scales both amplitudes (1 = as the game sent them) before
// they are clamped to 0..1. With both amplitudes at step 0 the bytes are the neutral value's, whatever the frequencies.
void rumble_hd_encode(const RumbleHdValue *v, float strength, uint8_t out[RUMBLE_HD_SIDE]);
// A report's data from the game's newest value per side (v[0] left, v[1] right). live[s] 0: that side is at rest
// (never sent, stale, or vibration not permitted). one: the controller has a single actuator (one Joy-Con): the
// stronger side's value goes into both halves.
void rumble_hd_data(const RumbleHdValue v[2], const int live[2], float strength, int one, uint8_t out[RUMBLE_HD_DATA]);
// The output report: id, number (0..15, going round), data, zeros up to n bytes (n >= RUMBLE_HD_REPORT).
void rumble_hd_report(const uint8_t data[RUMBLE_HD_DATA], unsigned number, uint8_t *out, unsigned n);
// What one controller is to get and what it got. All zero at the start.
typedef struct {
uint8_t want[RUMBLE_HD_DATA]; // the newest data from the game (rumble_hd_post) ...
uint64_t want_at; // ... and when it came
int have; // ... once there is one
uint8_t sent[RUMBLE_HD_DATA]; // the data of the last report written (rumble_hd_sent) ...
uint64_t sent_at; // ... and when
int any; // ... once there is one
int neutral_left; // neutral reports still to write after the last one
} RumbleHd;
// The game's newest data: it replaces what was not written yet (nothing is queued).
void rumble_hd_post(RumbleHd *h, const uint8_t data[RUMBLE_HD_DATA], uint64_t now);
// 1 when a report is to be written at `now`, with its data in out. on 0: the controller gets the neutral value whatever
// the game sent (the setting is off, the process ends). A changed value waits until gap_ns have passed since the last
// report; a value that still holds is written again every RUMBLE_HD_REFRESH_NS, since the actuators stop by themselves
// when no report comes; data older than RUMBLE_HD_STALE_NS is neutral; the neutral value is written
// RUMBLE_HD_NEUTRAL_REPORTS times, gap_ns apart, and then nothing until the game posts something else.
int rumble_hd_due(const RumbleHd *h, int on, uint64_t now, uint64_t gap_ns, uint8_t out[RUMBLE_HD_DATA]);
// The report with data was written at `now`.
void rumble_hd_sent(RumbleHd *h, const uint8_t data[RUMBLE_HD_DATA], uint64_t now);
// 1 when nothing is to be written until the next rumble_hd_post (or until `on` changes).
int rumble_hd_idle(const RumbleHd *h, int on, uint64_t now);
// 1 while the last report written was not the neutral value: the actuators may still be running.
int rumble_hd_buzzing(const RumbleHd *h);
// Another controller takes the reports: what was written no longer counts, the game's newest data stays.
void rumble_hd_forget(RumbleHd *h);

201
tests/rumble_hd_check.c Normal file
View File

@@ -0,0 +1,201 @@
// runtime/rumble_hd.c: a vibration value as the bytes of a linear actuator's rumble report (known values, the clamps,
// the neutral value), a report's data from the two sides, and which reports are written when the game sends a batch.
// Built and run by tests/rumble_hd_check.py; prints each failed check and exits 1 on any. With --sweep it prints
// values and their bytes, one per line, for the script to decode with formulae of its own.
#include <math.h>
#include <stdio.h>
#include <string.h>
#include "rumble_hd.h"
static int fails;
#define CHECK(c, ...) do { if (!(c)) { fails++; printf("FAIL line %d: ", __LINE__); printf(__VA_ARGS__); printf("\n"); } } while (0)
static int enc_is(float al, float fl, float ah, float fh, float strength, uint8_t b0, uint8_t b1, uint8_t b2, uint8_t b3,
uint8_t got[4]) {
RumbleHdValue v = {al, fl, ah, fh};
rumble_hd_encode(&v, strength, got);
return got[0] == b0 && got[1] == b1 && got[2] == b2 && got[3] == b3;
}
#define ENC(al, fl, ah, fh, st, b0, b1, b2, b3) do { uint8_t g_[4]; \
CHECK(enc_is(al, fl, ah, fh, st, b0, b1, b2, b3, g_), "%g@%g Hz %g@%g Hz x%g gave %02x %02x %02x %02x, expected %02x %02x %02x %02x", \
(double)(al), (double)(fl), (double)(ah), (double)(fh), (double)(st), g_[0], g_[1], g_[2], g_[3], b0, b1, b2, b3); } while (0)
static void sweep(void) {
static const float amps[] = {0, 0.001f, 0.0038f, 0.004f, 0.006f, 0.0078f, 0.0095f, 0.0098f, 0.012f, 0.02f, 0.05f, 0.09f,
0.113f, 0.116f, 0.15f, 0.2f, 0.226f, 0.229f, 0.25f, 0.3f, 0.4f, 0.5f, 0.66f, 0.8f, 0.9f,
0.99f, 1, 1.3f, 4};
for (size_t a = 0; a < sizeof amps / sizeof *amps; a++)
for (size_t b = 0; b < sizeof amps / sizeof *amps; b += 3)
for (float f = 20; f < 3000; f *= 1.0717f) {
RumbleHdValue v = {amps[a], f, amps[b], f * 1.9f};
uint8_t o[4];
rumble_hd_encode(&v, 1, o);
printf("%.9g %.9g %.9g %.9g %u %u %u %u\n", (double)v.amp_low, (double)v.freq_low, (double)v.amp_high,
(double)v.freq_high, o[0], o[1], o[2], o[3]);
}
}
#define MS 1000000ull
int main(int argc, char **argv) {
if (argc > 1 && !strcmp(argv[1], "--sweep")) { sweep(); return 0; }
// ---- known values
// The neutral value, as the game sends it and as the controller expects it.
ENC(0, 160, 0, 320, 1, 0x00, 0x01, 0x40, 0x40);
CHECK(!memcmp(rumble_hd_neutral, "\x00\x01\x40\x40\x00\x01\x40\x40", 8), "the neutral data is not 00 01 40 40 twice");
// Both bands at 150 Hz and amplitude 0.9: frequency step 125 (low 0x3d, high 0x74), amplitude step 95.
ENC(0.9f, 150, 0.9f, 150, 1, 0x74, 0xbe, 0xbd, 0x6f);
// Full amplitude at the neutral frequencies: amplitude step 100, the last one.
ENC(1, 160, 1, 320, 1, 0x00, 0xc9, 0x40, 0x72);
// Amplitude 0.5 is step 68; one band alone leaves the other at step 0.
ENC(0.5f, 160, 0, 320, 1, 0x00, 0x01, 0x40, 0x62);
ENC(0, 160, 0.5f, 320, 1, 0x00, 0x89, 0x40, 0x40);
// An odd amplitude step puts its low bit on top of the low frequency byte: 0.245 is step 35.
ENC(0.245f, 160, 0.245f, 320, 1, 0x00, 0x47, 0xc0, 0x51);
// ---- the clamps
// Frequencies outside a band go to its ends: low 1..0x7f, high 4..0x1fc.
ENC(0.5f, 10, 0.5f, 5000, 1, 0xfc, 0x89, 0x01, 0x62);
ENC(0.5f, 5000, 0.5f, 10, 1, 0x04, 0x88, 0x7f, 0x62);
ENC(0.5f, RUMBLE_HD_LOW_MIN, 0.5f, RUMBLE_HD_HIGH_MIN, 1, 0x04, 0x88, 0x01, 0x62);
ENC(0.5f, RUMBLE_HD_LOW_MAX, 0.5f, RUMBLE_HD_HIGH_MAX, 1, 0xfc, 0x89, 0x7f, 0x62);
ENC(0.5f, 0, 0.5f, -3, 1, 0x04, 0x88, 0x01, 0x62);
ENC(0.5f, NAN, 0.5f, NAN, 1, 0x04, 0x88, 0x01, 0x62);
// Amplitudes above 1, by themselves or through the strength, stop at step 100; the strength scales below it.
ENC(7, 160, 7, 320, 1, 0x00, 0xc9, 0x40, 0x72);
ENC(0.5f, 160, 0.5f, 320, 3, 0x00, 0xc9, 0x40, 0x72);
ENC(1, 160, 1, 320, 0.5f, 0x00, 0x89, 0x40, 0x62);
ENC(INFINITY, 160, INFINITY, 320, 1, 0x00, 0xc9, 0x40, 0x72);
// No amplitude is the neutral value whatever the frequencies say: negative, NaN, too small, strength 0.
ENC(0, 55, 0, 1000, 1, 0x00, 0x01, 0x40, 0x40);
ENC(-1, 55, -0.5f, 1000, 1, 0x00, 0x01, 0x40, 0x40);
ENC(NAN, 55, NAN, 1000, 1, 0x00, 0x01, 0x40, 0x40);
ENC(0.003f, 55, 0.001f, 1000, 1, 0x00, 0x01, 0x40, 0x40);
ENC(1, 55, 1, 1000, 0, 0x00, 0x01, 0x40, 0x40);
ENC(1, 55, 1, 1000, -2, 0x00, 0x01, 0x40, 0x40);
// ---- the amplitude scale
static const struct { int step; float amp; } table[] = {{0, 0}, {1, 0.007843f}, {2, 0.011823f}, {6, 0.023648f},
{15, 0.112491f}, {16, 0.117471f}, {31, 0.224982f}, {32, 0.229904f}, {64, 0.459808f}, {100, 1.002867f}};
for (size_t i = 0; i < sizeof table / sizeof *table; i++) {
float a = rumble_hd_step_amp(table[i].step);
CHECK(fabsf(a - table[i].amp) <= table[i].amp * 0.003f, "step %d is %f, the table says %f", table[i].step, (double)a,
(double)table[i].amp);
}
for (int k = 0; k <= RUMBLE_HD_AMP_STEPS; k++) {
CHECK(rumble_hd_amp_step(rumble_hd_step_amp(k)) == k, "step %d's amplitude %f gives step %d", k,
(double)rumble_hd_step_amp(k), rumble_hd_amp_step(rumble_hd_step_amp(k)));
if (k) CHECK(rumble_hd_step_amp(k) > rumble_hd_step_amp(k - 1), "step %d is not above step %d", k, k - 1);
}
int top = 0;
for (float a = -1; a < 20; a += 0.0007f) {
int k = rumble_hd_amp_step(a);
if (k > top) top = k;
CHECK(k >= 0 && k <= RUMBLE_HD_AMP_STEPS, "amplitude %f gives step %d", (double)a, k);
}
CHECK(top == RUMBLE_HD_AMP_STEPS && RUMBLE_HD_AMP_STEPS == 100, "the highest step reached is %d", top);
// ---- a report's data from the two sides
RumbleHdValue v[2] = {{0.5f, 160, 0, 320}, {0, 160, 0.9f, 150}};
int both[2] = {1, 1}, left[2] = {1, 0}, none[2] = {0, 0};
uint8_t d[8];
rumble_hd_data(v, both, 1, 0, d);
CHECK(!memcmp(d, "\x00\x01\x40\x62\x74\xbe\x40\x40", 8), "two sides: %02x %02x %02x %02x | %02x %02x %02x %02x", d[0], d[1],
d[2], d[3], d[4], d[5], d[6], d[7]);
rumble_hd_data(v, left, 1, 0, d);
CHECK(!memcmp(d, "\x00\x01\x40\x62\x00\x01\x40\x40", 8), "a side at rest is not neutral");
rumble_hd_data(v, none, 1, 0, d);
CHECK(!memcmp(d, rumble_hd_neutral, 8), "both sides at rest are not neutral");
rumble_hd_data(v, both, 1, 1, d); // one actuator: the stronger side (the right one, 0.9) in both halves
CHECK(!memcmp(d, "\x74\xbe\x40\x40\x74\xbe\x40\x40", 8), "one actuator: %02x %02x %02x %02x | %02x %02x %02x %02x", d[0],
d[1], d[2], d[3], d[4], d[5], d[6], d[7]);
rumble_hd_data(v, left, 1, 1, d); // ... and the side that is not at rest when the stronger one is
CHECK(!memcmp(d, "\x00\x01\x40\x62\x00\x01\x40\x62", 8), "one actuator, right side at rest");
rumble_hd_data(v, both, 0, 0, d);
CHECK(!memcmp(d, rumble_hd_neutral, 8), "strength 0 is not neutral");
// ---- the output report
uint8_t r[49];
memset(r, 0xee, sizeof r);
rumble_hd_report((const uint8_t *)"\x74\xbe\xbd\x6f\x00\x01\x40\x40", 0x25, r, sizeof r);
CHECK(r[0] == 0x10 && r[1] == 0x05 && !memcmp(r + 2, "\x74\xbe\xbd\x6f\x00\x01\x40\x40", 8), "report head %02x %02x", r[0], r[1]);
for (int i = 10; i < 49; i++) CHECK(r[i] == 0, "report byte %d is %02x", i, r[i]);
// ---- from a batch to the reports written: a tick every 5 ms, 15 ms between reports
static const uint8_t A[8] = {1, 2, 3, 4, 5, 6, 7, 8}, B[8] = {9, 9, 9, 9, 9, 9, 9, 9}, C[8] = {3, 3, 3, 3, 3, 3, 3, 3},
D[8] = {4, 4, 4, 4, 4, 4, 4, 4}, E[8] = {5, 5, 5, 5, 5, 5, 5, 5};
RumbleHd h = {0};
uint8_t o[8];
uint64_t t0 = 1000 * MS;
CHECK(!rumble_hd_due(&h, 1, t0, RUMBLE_HD_GAP_NS, o) && rumble_hd_idle(&h, 1, t0), "a report is due before the game sent anything");
rumble_hd_post(&h, rumble_hd_neutral, t0);
CHECK(!rumble_hd_due(&h, 1, t0, RUMBLE_HD_GAP_NS, o) && rumble_hd_idle(&h, 1, t0), "the neutral value is written to a controller at rest");
// three values in one batch: the newest is written, at once
rumble_hd_post(&h, A, t0);
rumble_hd_post(&h, B, t0);
rumble_hd_post(&h, C, t0 + MS);
struct { uint64_t at; uint8_t d[8]; } rep[64];
int n = 0;
for (uint64_t t = t0 + MS; t <= t0 + 400 * MS; t += 5 * MS) {
if (t == t0 + 6 * MS) rumble_hd_post(&h, D, t); // 5 ms after the first report: too soon to write
if (t == t0 + 11 * MS) rumble_hd_post(&h, E, t); // replaces D before D was written
if (rumble_hd_due(&h, 1, t, RUMBLE_HD_GAP_NS, o) && n < 64) {
rep[n].at = t - t0;
memcpy(rep[n++].d, o, 8);
rumble_hd_sent(&h, o, t);
}
}
CHECK(n >= 2 && rep[0].at == MS && !memcmp(rep[0].d, C, 8), "the first report is not the batch's newest value, at once");
CHECK(n >= 2 && rep[1].at == 16 * MS && !memcmp(rep[1].d, E, 8), "the second report is not the newest value 15 ms later (at %llu ms)",
n >= 2 ? (unsigned long long)(rep[1].at / MS) : 0ull);
int held = 0, neutral = 0;
uint64_t last_e = 0, first_neutral = 0, last_neutral = 0;
for (int i = 0; i < n; i++) {
CHECK(memcmp(rep[i].d, A, 8) && memcmp(rep[i].d, B, 8) && memcmp(rep[i].d, D, 8), "a replaced value was written at %llu ms",
(unsigned long long)(rep[i].at / MS));
if (i) CHECK(rep[i].at - rep[i - 1].at >= RUMBLE_HD_GAP_NS, "two reports %llu ms apart", (unsigned long long)((rep[i].at - rep[i - 1].at) / MS));
if (!memcmp(rep[i].d, E, 8)) {
if (last_e) CHECK(rep[i].at - last_e == RUMBLE_HD_REFRESH_NS, "a held value was written again after %llu ms",
(unsigned long long)((rep[i].at - last_e) / MS));
last_e = rep[i].at, held++;
CHECK(!neutral, "a value after the neutral one");
}
if (!memcmp(rep[i].d, rumble_hd_neutral, 8)) {
if (!neutral++) first_neutral = rep[i].at;
last_neutral = rep[i].at;
}
}
// E came at 11 ms and is stale 250 ms later: written at 16 ms and every 30 ms until then
CHECK(held == 9, "the held value was written %d times", held);
CHECK(neutral == RUMBLE_HD_NEUTRAL_REPORTS, "the neutral value was written %d times", neutral);
CHECK(first_neutral > 261 * MS && first_neutral <= 261 * MS + RUMBLE_HD_GAP_NS, "the neutral value came %llu ms in",
(unsigned long long)(first_neutral / MS));
CHECK(last_neutral - first_neutral == 2 * RUMBLE_HD_GAP_NS, "the neutral reports are not 15 ms apart");
CHECK(rumble_hd_idle(&h, 1, t0 + 400 * MS) && !rumble_hd_buzzing(&h), "not idle after the neutral reports");
// the path turned off while the game sends: the neutral value, whatever the game's data
RumbleHd g = {0};
rumble_hd_post(&g, A, t0);
CHECK(rumble_hd_due(&g, 1, t0, RUMBLE_HD_GAP_NS, o) && !memcmp(o, A, 8), "a first value is not due at once");
rumble_hd_sent(&g, o, t0);
CHECK(!rumble_hd_idle(&g, 1, t0 + MS) && rumble_hd_buzzing(&g), "idle while a value is held");
CHECK(!rumble_hd_due(&g, 0, t0 + 5 * MS, RUMBLE_HD_GAP_NS, o), "off: a report inside the gap");
CHECK(rumble_hd_due(&g, 0, t0 + 15 * MS, RUMBLE_HD_GAP_NS, o) && !memcmp(o, rumble_hd_neutral, 8), "off: no neutral report");
CHECK(rumble_hd_due(&g, 0, t0 + 6 * MS, 5 * MS, o) && !memcmp(o, rumble_hd_neutral, 8), "a 5 ms gap is not honoured");
rumble_hd_sent(&g, o, t0 + 15 * MS);
CHECK(!rumble_hd_buzzing(&g) && !rumble_hd_idle(&g, 0, t0 + 16 * MS), "idle before the neutral value was repeated");
// back on with the game's data still fresh: it is written again
CHECK(rumble_hd_due(&g, 1, t0 + 30 * MS, RUMBLE_HD_GAP_NS, o) && !memcmp(o, A, 8), "on again: the game's value is not due");
rumble_hd_sent(&g, o, t0 + 30 * MS);
// another controller: what was written is forgotten, the game's value is due at once
rumble_hd_forget(&g);
CHECK(!rumble_hd_buzzing(&g), "buzzing after forget");
CHECK(rumble_hd_due(&g, 1, t0 + 31 * MS, RUMBLE_HD_GAP_NS, o) && !memcmp(o, A, 8), "after forget: the value is not due at once");
CHECK(!rumble_hd_due(&g, 1, t0 + 300 * MS, RUMBLE_HD_GAP_NS, o) && rumble_hd_idle(&g, 1, t0 + 300 * MS),
"after forget: a stale value is written to a controller that got nothing");
printf(fails ? "rumble hd: %d failures\n" : "rumble hd: ok\n", fails);
return fails != 0;
}

118
tests/rumble_hd_check.py Normal file
View File

@@ -0,0 +1,118 @@
"""HD rumble for controllers with linear actuators (runtime/rumble_hd.c): builds it with tests/rumble_hd_check.c and
checks
- known values: the neutral value, full amplitude, single bands, an odd amplitude step;
- the clamps: frequencies to each band's ends, amplitudes to 0..1 with the last step at 100, no amplitude as the
neutral value;
- a report's data from the two sides, for two actuators and for one, and the output report's layout;
- from a batch to the reports written: the newest value at once, replaced values never, a held value again every
30 ms, the neutral value three times once the game stops, then nothing.
Then it decodes a sweep of encoded values with formulae of its own (this script's, not the C file's): each frequency
comes back within half a step of the clamped input, each amplitude as the step nearest to it, and no amplitude step is
above 100.
No game files, no SDL, no controller. Usage: python tests/rumble_hd_check.py [--cc <clang>]
"""
import argparse
import math
import os
import subprocess
import sys
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
MSYS_BIN = Path(r'C:\msys64\ucrt64\bin')
LOW = (40.875885, 626.286133) # Hz, the low band's ends
HIGH = (81.75177, 1252.572266) # ... and the high band's
def step_amp(k):
"""The amplitude of step k, from the published table's rule: step 1 alone, then quarter, sixteenth and
thirty-second octaves."""
if k == 0:
return 0.0
if k == 1:
return 0.007843
if k < 16:
return 0.011823 * 2 ** ((k - 2) / 4)
if k < 32:
return 2 ** (k / 16) / 17
return 2 ** (k / 32) / 8.7
def decode(b):
"""Four report bytes to (amp_low step, freq_low Hz, amp_high step, freq_high Hz)."""
hf = b[0] | (b[1] & 1) << 8
ha = b[1] >> 1
lf = b[2] & 0x7f
la = (b[3] - 0x40) * 2 + (b[2] >> 7)
return la, 10 * 2 ** ((lf + 0x40) / 32), ha, 10 * 2 ** ((hf / 4 + 0x60) / 32)
def nearest_step(a):
if not a >= 0.007843 / 2:
return 0
a = min(a, 1.0)
return min(range(1, 101), key=lambda k: abs(math.log(a / step_amp(k))))
def check_sweep(lines):
fails = 0
half = 2 ** (1 / 64) * 1.0005 # half a frequency step, and the rounding of a float
for line in lines:
f = line.split()
al, fl, ah, fh = (float(x) for x in f[:4])
b = [int(x) for x in f[4:]]
la, dfl, ha, dfh = decode(b)
what = f'{al}@{fl} Hz {ah}@{fh} Hz -> {" ".join("%02x" % x for x in b)}'
if not (0 <= la <= 100 and 0 <= ha <= 100 and 0x40 <= b[3] <= 0x72):
print(f'FAIL {what}: amplitude steps {la}, {ha} outside 0..100')
fails += 1
continue
for name, a, got in (('low', al, la), ('high', ah, ha)):
want = nearest_step(a)
# at a boundary between two steps either neighbour is the nearest
if got != want and (got == 0 or want == 0 or
abs(abs(math.log(min(a, 1.0) / step_amp(got))) -
abs(math.log(min(a, 1.0) / step_amp(want)))) > 2e-3):
print(f'FAIL {what}: {name} amplitude is step {got}, the nearest is {want}')
fails += 1
if la == 0 and ha == 0:
if b != [0x00, 0x01, 0x40, 0x40]:
print(f'FAIL {what}: no amplitude is not the neutral value')
fails += 1
continue
for name, hz, got, (lo, hi) in (('low', fl, dfl, LOW), ('high', fh, dfh, HIGH)):
want = min(max(hz, lo), hi)
if not want / half <= got <= want * half:
print(f'FAIL {what}: {name} frequency decodes to {got:.2f} Hz, expected {want:.2f}')
fails += 1
return fails
def main():
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument('--cc', help='the C compiler (default: MSYS2 UCRT64 clang on Windows, clang elsewhere)')
args = ap.parse_args()
win = os.name == 'nt'
cc = args.cc or os.environ.get('CC') or (str(MSYS_BIN / 'clang.exe') if win and MSYS_BIN.exists() else 'clang')
env = dict(os.environ)
if win and MSYS_BIN.exists():
env['PATH'] = str(MSYS_BIN) + os.pathsep + env.get('PATH', '')
work = ROOT / 'build' / 'test' / 'rumble_hd'
work.mkdir(parents=True, exist_ok=True)
exe = work / ('rumble_hd_check.exe' if win else 'rumble_hd_check')
subprocess.check_call([cc, '-O1', '-Wall', '-Wextra', '-fno-strict-aliasing', '-I', str(ROOT / 'runtime'),
str(ROOT / 'tests' / 'rumble_hd_check.c'), str(ROOT / 'runtime' / 'rumble_hd.c'),
'-o', str(exe)] + ([] if win else ['-lm']), env=env)
rc = subprocess.run([str(exe)], env=env).returncode
out = subprocess.run([str(exe), '--sweep'], env=env, capture_output=True, text=True, check=True).stdout.splitlines()
fails = check_sweep(out)
print(f'rumble hd sweep: {len(out)} values decoded, ' + (f'{fails} failures' if fails else 'ok'))
return 1 if rc or fails or not out else 0
if __name__ == '__main__':
sys.exit(main())