Suduxu
Reference

Data Models

Core runtime data structures and configuration contracts used across Suduxu.

Behaviour Configuration

The SuduxuBehaviourConfiguration defines how the runtime is initialized and how it connects to the underlying ABI layer.

It is required before calling any lifecycle or runtime functions.

SuduxuBehaviourConfiguration

Represents the primary startup configuration for a Suduxu runtime instance.

pub struct SuduxuBehaviourConfiguration {
    pub dll_path: PathBuf,
    pub default_id: u16,
}

SuduxuConfig

Represents the runtime configuration loaded from suduxu.json or provided by the host environment.

pub struct SuduxuConfig {
    pub server: Server,
    pub logging: Logging,
    pub security: Security,
    pub file_sharing: FileSharing,
    pub devices: Devices,
    pub screen_capture: ScreenCapture,
    pub sensors: Sensors,
    pub developer: Developer,
    pub health_check: HealthCheck,
}

pub struct Server {
    pub address: String,
    pub port: Option<u16>,
    pub tcp_port: Option<u16>,
    pub udp_port: Option<u16>,
    pub file_port: Option<u16>,
    pub connection_strategy: ConnectionStrategy,
    pub list: Option<Vec<String>>,
    pub rate_limit: RateLimit,
}

pub struct Logging {
    pub debug_level: LogLevel,
    pub log_file: Option<String>,
    pub max_log_size: Option<u64>,
    pub log_to_console: bool,
}

pub struct Security {
    pub enabled: bool,
    pub password: Option<u32>
}

pub struct FileSharing {
    pub enabled: bool,
    pub shared_directory: Option<String>,
    pub files: Option<Vec<SharedFile>>,
    pub initially_loaded: Option<Vec<String>>
}

pub struct Devices {
    pub initially_send_sensor_data: bool,
    pub max_devices: Option<u16>,
    pub allowed_device_types: Vec<OsType>,
    pub initial_frame_rate: u16,
}

pub struct ScreenCapture {
    pub enabled: bool,
    pub capture_on_server: bool,
    pub capture_directory: Option<String>,
}

pub struct Sensors {
    pub accelerometer: bool,
    pub gyroscope: bool,
    pub magnetometer: bool,
    pub temperature: bool,
    pub humidity: bool,
    pub pressure: bool,
    pub light: bool,
}

pub struct Developer {
    pub prefer_cli: bool,
    pub allow_mocked_sensors: bool,
    pub allow_mocked_buttons: bool,
}

pub struct HealthCheck {
    pub server: HealthCheckConfig,
    pub client: HealthCheckConfig,
}

pub enum ConnectionStrategy {
    Whitelist,
    Blacklist,
    Open,
    #[serde(other)]
    Invalid
}

pub struct RateLimit {
    pub enabled: bool,
    pub max_tcp_requests_per_minute: Option<u16>,
}

pub enum OsType {
    Android,
    #[serde(rename = "iOS")]
    IOS,
    Windows,
    Linux,
    #[serde(rename = "macOS")]
    MacOS,
    Unknown,
    #[serde(other)]
    Other,
}

pub struct HealthCheckConfig {
    pub enabled: bool,
    pub interval_ms: Option<u64>,
    pub timeout_ms: Option<u64>,
}

pub struct SharedFile {
    pub name: String,
    pub path: String,
    pub r#type: SharedFileType,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub theme_constraints: Option<ThemeConstraints>
}

pub enum SharedFileType {
    Audio,

    #[serde(rename = "Lua-Theme")]
    LuaTheme,

    #[serde(rename = "XML-Theme")]
    XMLTheme,

    Screenshot,
    #[serde(other)]
    Invalid
}

pub struct ThemeConstraints {
    pub max_width: Option<u16>,
    pub min_width: Option<u16>,
}
public class SuduxuConfig
{
    public Server server;
    public Logging logging;
    public Security security;
    public FileSharing fileSharing;
    public Devices devices;
    public ScreenCapture screenCapture;
    public Sensors sensors;
    public Developer developer;
    public HealthCheck healthCheck;
}

public class Server
{
    public string address;
    public ushort? port;
    public ushort? tcpPort;
    public ushort? udpPort;
    public ushort? filePort;
    public ConnectionStrategy connectionStrategy;
    public List<string> list;
    public RateLimit rateLimit;
}

public class Logging
{
    public LogLevel debugLevel;
    public string logFile;
    public ulong? maxLogSize;
    public bool logToConsole;
}

public class Security
{
    public bool enabled;
    public uint? password;
}

public class FileSharing
{
    public bool enabled;
    public string sharedDirectory;
    public List<SharedFile> files;
    public List<string> initiallyLoaded;
}

public class Devices
{
    public bool initiallySendSensorData;
    public ushort? maxDevices;
    public List<Os> allowedDeviceTypes;
    public ushort initialFrameRate;
}

public class ScreenCapture
{
    public bool enabled;
    public bool captureOnServer;
    public string captureDirectory;
}

public class Sensors
{
    public bool accelerometer;
    public bool gyroscope;
    public bool magnetometer;
    public bool temperature;
    public bool humidity;
    public bool pressure;
    public bool light;
}

public class Developer
{
    public bool preferCli;
    public bool allowMockedSensors;
    public bool allowMockedButtons;
}

public class HealthCheck
{
    public HealthCheckConfig server;
    public HealthCheckConfig client;
}

public enum ConnectionStrategy
{
    Whitelist,
    Blacklist,
    Open
}

public class RateLimit
{
    public bool enabled;
    public ushort? maxTcpRequestsPerMinute;
}

public class SharedFile
{
    public string name;
    public string path;
    public SharedFileType type;
    public ThemeConstraints themeConstraints;
}

[JsonConverter(typeof(Newtonsoft.Json.Converters.StringEnumConverter))]
public enum SharedFileType
{
    Audio,
    [EnumMember(Value = "HTML-Theme")]
    HTMLTheme,

    [EnumMember(Value = "XML-Theme")]
    XMLTheme
}

public class ThemeConstraints
{
    public ushort? minWidth;
    public ushort? maxWidth;
}

public class HealthCheckConfig
{
    public bool enabled;
    public ulong? intervalMs;
    public ulong? timeoutMs;
}

SuduxuConfig might change at runtime based on specified fields (e.g. password generation)

AddressObject

The AddressObject represents the network addresses used by the runtime for different communication channels.

pub struct AddressObject {
    pub tcp: String,
    pub udp: String,
    pub file: Option<String>,
}
public class AddressObject
{
    public string tcp;
    public string udp;
    public string file;
}

QrCode

The QrCode object represents the QR code information generated by the runtime for client connection.

pub struct QrCode {
    pub pixels: Vec<u8>,
    pub width: u32,
}

Payload Objects

Payload objects are used to send structured data between the native runtime and the clients.

Payload

The Payload object represents a generic data structure for sending information between the runtime and clients.

pub struct Payload {
    #[serde(default)]
    #[serde(skip_serializing_if = "is_zero")]
    pub id: u16,
    name: String,
    values: Value,
}
public class Payload
{
    public ushort id;
    public string name;
    public JToken values;
}

VibrationStrength

The VibrationStrength object defines the intensity of a vibration command sent to a client device.

pub enum VibrationStrength {
    Light,
    Medium,
    Heavy
}
public enum VibrationStrength
{
    Light,
    Medium,
    Heavy
}

Based on the operating system (mobile only) this leaves us with the following mappings:

StrengthAndroidiOS
LightAmplitude: 64UIImpactFeedbackStyle.UIImpactFeedbackStyleLight
MediumAmplitude: 128UIImpactFeedbackStyle.UIImpactFeedbackStyleMedium
HeavyAmplitude: 256UIImpactFeedbackStyle.UIImpactFeedbackStyleHeavy

Note that the VibrationStrength is only compatible with the VibrationTypes VibrationType.Custom and VibrationType.Impact.

VibrationType

The VibrationType object defines the pattern of a vibration command sent to a client device.

pub enum VibrationType {
    Impact,
    Notification,
    Selection,
    Custom
}
public enum VibrationType
{
    Impact,
    Notification,
    Selection,
    Custom
}

Based on the operating system (mobile only) this leaves us with the following mappings:

TypeAndroidiOS
ImpactVibrationEffect.createOneShot(durationMs, amplitude)UIImpactFeedbackGenerator (Style based on Strength)
NotificationAPI 29+: VibrationEffect.EFFECT_HEAVY_CLICK

Fallback: VibrationEffect.createOneShot(80, amplitude)
UINotificationFeedbackGenerator (UINotificationFeedbackTypeSuccess)
SelectionAPI 29+: VibrationEffect.EFFECT_TICK

Fallback: VibrationEffect.createOneShot(40, amplitude)
UISelectionFeedbackGenerator
CustomVibrationEffect.createOneShot(durationMs, amplitude)UIImpactFeedbackGenerator (Style based on Strength)

Logging

Log messages sent from the runtime to clients include a log level to allow for filtering and categorization.

LogLevel

The LogLevel object defines the severity of a log message sent to a client device.

pub enum LogLevel {
    Debug,
    Info,
    Warn,
    Error
}
public enum LogLevel
{
    Debug,
    Info,
    Warn,
    Error
}

Input

Real-time input data from client devices is structured into specific payloads for consistent handling.

ButtonInput

The ButtonInput object represents the state of a button input event from a client device.

pub struct ButtonInput {
    pub mocked: bool,
    pub r#type: ButtonInputType,
    pub state: ButtonInputState,
}
public class ButtonInput
{
    public bool mocked;
    public ButtonInputType type;
    public ButtonInputState state;
}

ButtonInputType

The ButtonInputType enum defines the type of button input received from a client device.

pub enum ButtonInputType {
    None,
    Up,
    Down,
    Left,
    Right,
    A,
    One,
    Two,
    Screenshot,
    Plus,
    Minus,
}
public enum ButtonInputType
{
    None = 0,
    Up = 1,
    Down = 2,
    Left = 3,
    Right = 4,
    A = 5,
    One = 6,
    Two = 7,
    Screenshot = 8,
    Plus = 9,
    Minus = 10,
}

ButtonInputState

The ButtonInputState enum defines the state of a button input event received from a client device.

pub enum ButtonInputState {
    None,
    Down,
    Pressed,
    Up,
    Cancel
}
public enum ButtonInputState {
    None = 0,
    Down = 1,
    Pressed = 2,
    Up = 3,
    Cancel = 4,
}

SensorDataRaw

The SensorDataRaw object represents raw sensor data received from a client device.

#[derive(Copy, Clone, Serialize, Deserialize, Debug)]
pub struct SensorDataRaw {
    pub id: u16,

    pub mocked: u8, // 0 for false, 1 for true

    pub ax: f32,
    pub ay: f32,
    pub az: f32,

    pub gx: f32,
    pub gy: f32,
    pub gz: f32,
    pub gw: f32,

    pub mx: f32,
    pub my: f32,
    pub mz: f32,

    pub temperature: f32,
    pub humidity: f32,
    pub pressure: f32,
    pub light: f32,
}
public struct SensorDataRaw
{
    public ushort id;

    public byte mocked;

    public float ax;
    public float ay;
    public float az;

    public float gx;
    public float gy;
    public float gz;
    public float gw;

    public float mx;
    public float my;
    public float mz;

    public float temperature;
    public float humidity;
    public float pressure;
    public float light;
}

The mocked field is represented as a byte (0 or 1) for compatibility. If no data is present, the fields will be set to 0.

JoystickData

The JoystickData object represents joystick input data received from a client device.

pub struct JoystickData {
    pub x: f32,
    pub y: f32,
    pub angle_deg: f32,
    pub magnitude: f32
}
public class JoystickData
{
    public float x;
    public float y;
    public float angleDeg;
    public float magnitude;
}

Device State

Device state data models represent the current status and telemetry of connected client devices.

Battery

The Battery object represents the battery status of a connected client device.

pub struct Battery {
    pub level: u8,
    pub charging_status: ChargingStatus
}
public class Battery
{
    public sbyte level;

    [JsonProperty("charging_status")]
    public ChargingStatus chargingStatus;
}

ChargingStatus

The ChargingStatus enum defines the charging state of a connected client device's battery.

pub enum ChargingStatus {
    Charging,
    Discharging,
    Full,
    NotCharging,
    #[default]
    Unknown,
}
public enum ChargingStatus
{
    Charging,
    Discharging,
    Full,
    NotCharging,
    Unknown,
}

Network

The Network object represents the network status of a connected client device.

pub struct Network {
    pub network_type: NetworkType
}
public class Network
{
    public NetworkType networkType;
}

NetworkType

The NetworkType enum defines the type of network connectivity of a connected client device.

pub enum NetworkType {
    Wifi,
    Mobile,
    Ethernet,
    Bluetooth,
    VPN,
    #[default]
    Unknown
}
public enum NetworkType
{
    Wifi,
    Mobile,
    Ethernet,
    Bluetooth,
    VPN,
    Unknown
}

On this page