Introduction to the StepManiaX SDK

The StepManiaX SDK supports C++ development for the StepManiaX dance platform.

Usage

You can either build the solution and link the resulting SMX.dll to your application, or import the source project and add it to your Visual Studio solution. The SDK interface is SMX.h.

See SMXSample for a sample application.

Up to two controllers are supported. SMX_GetInfo can be used to check which controllers are connected. Each pad argument to API calls can be 0 for the player 1 pad, or 1 for the player 2 pad.

HID support

The platform can be used as a regular USB HID input device, which works in any game that supports input remapping.

However, applications using this SDK to control the panels directly should ignore the HID interface, and instead use SMX_GetInputState to retrieve the input state.

Platform lights

The platform can have up to nine panels. Each panel has a grid of 4x4 RGB LEDs, which can be individually controlled at up to 30 FPS.

See SMX_SetLights2.

Update notes

2019-07-18-01: Added SMX_SetLights2. This is the same as SMX_SetLights, with an added parameter to specify the size of the buffer. This must be used to control the Gen4 pads which have additional LEDs.

Platform configuration

The platform configuration can be read and modified using SMX_GetConfig and SMX_SetConfig. Most of the platform configuration doesn't need to be accessed by applications, since users can use the SMXConfig application to manage their platform.

enabledSensors
Each platform can have up to nine panels in any configuration, but most devices have a smaller number of panels installed. If an application wants to adapt its UI to the user's panel configuration, see enabledSensors to detect which sensors are enabled.
Each panel has four sensors, and if a panel is disabled, all four of its sensors will be disabled. Disabling individual sensors is possible, but removing individual sensors reduces the performance of the pad and isn't recommended.
Note that this indicates which panels the player is using for input. Other panels may still have lights support, and the application should always send lights data for all possible panels even if it's not being used for input.

Reference

void SMX_Start(SMXUpdateCallback UpdateCallback, void *pUser);

Initialize, and start searching for devices.

UpdateCallback will be called when something happens: connection or disconnection, inputs changed, configuration updated, test data updated, etc. It doesn't specify what's changed, and the user should check all state that it's interested in.

This is called asynchronously from a helper thread, so the receiver must be thread-safe.

void SMX_Stop();

Shut down and disconnect from all devices. This will wait for any user callbacks to complete, and no user callbacks will be called after this returns.

void SMX_SetLogCallback(SMXLogCallback callback);

Set a function to receive diagnostic logs. By default, logs are written to stdout. This can be called before SMX_Start, so it affects any logs sent during initialization.

void SMX_GetInfo(int pad, SMXInfo *info);

Get info about a pad. Use this to detect which pads are currently connected.

uint16_t SMX_GetInputState(int pad);

Get a mask of the currently pressed panels.

void SMX_SetLights(const char lightsData[864]);

(deprecated)

Equivalent to SMX_SetLights2(lightsData, 864). SMX_SetLights2 should be used instead.

void SMX_SetLights2(const char *lightsData, int lightDataSize);

Update the lights. Both pads are always updated together. lightsData is a list of 8-bit RGB colors, one for each LED.

lightDataSize is the number of bytes in lightsData. This should be 1350 (2 pads * 9 panels * 25 lights * 3 RGB colors). For backwards-compatibility, this can also be 864.

25-LED panels have lights in the following order:

00  01  02  03
  16  17  18
04  05  06  07
  19  20  21
08  09  10  11
  22  23  24
12  13  14  15

16-LED panels have the same layout, ignoring LEDs 16 and up.

Panels are in the following order:

012 9AB
345 CDE
678 F01

Lights will update at up to 30 FPS. If lights data is sent more quickly, a best effort will be made to send the most recent lights data available, but the panels won't update more quickly.

The panels will return to automatic lighting if no lights are received for a while, so applications controlling lights should send light updates continually, even if the lights aren't changing.

For backwards compatibility, if lightDataSize is 864, the old 4x4-only order is used, which simply omits lights 16-24.

void SMX_ReenableAutoLights();

By default, the panels light automatically when stepped on. If a lights command is sent by the application, this stops happening to allow the application to fully control lighting. If no lights update is received for a few seconds, automatic lighting is reenabled by the panels.

SMX_ReenableAutoLights can be called to immediately reenable auto-lighting, without waiting for the timeout period to elapse. Games don't need to call this, since the panels will return to auto-lighting mode automatically after a brief period of no updates.

void SMX_GetConfig(int pad, SMXConfig *config);

Get the current controller's configuration.

void SMX_SetConfig(int pad, const SMXConfig *config);

Update the current controller's configuration. This doesn't block, and the new configuration will be sent in the background. SMX_GetConfig will return the new configuration as soon as this call returns, without waiting for it to actually be sent to the controller.

void SMX_FactoryReset(int pad);

Reset a pad to its original configuration.

void SMX_ForceRecalibration(int pad);

Request an immediate panel recalibration. This is normally not necessary, but can be helpful for diagnostics.

void SMX_SetTestMode(int pad, SensorTestMode mode);
bool SMX_GetTestData(int pad, SMXSensorTestModeData *data);

Set a panel test mode and request test data. This is used by the configuration tool.