haply 1.1.0

Haply Robotics Client Library for the Inverse Service
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311

//! Outgoing command types, configure types, and the service message structure.

use serde::{Deserialize, Serialize};
use ts_rs::TS;

use super::base_types::*;
use super::devices::CoordinateSystem;
use super::navigation::NavigationConfigure;
use super::sdf::{SdfCommand, SdfHfxObject, SdfOutputConfigure};

// ============================================================
// Convenience input types for public API
// ============================================================

#[derive(Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct ForceInput {
    pub device_id: String,
    pub forces: Force,
}

#[derive(Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct PositionInput {
    pub device_id: String,
    pub positions: Linear3D,
}

#[derive(Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct ExtensionDataInput {
    pub device_id: String,
    pub extension_data: Vec<i32>,
}

#[derive(Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct AngularTorqueInput {
    pub device_id: String,
    pub torques: Angular3D,
}

#[derive(Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct AngularPositionInput {
    pub device_id: String,
    pub angles: Angular3D,
}

// ============================================================
// Transform with optional sub-fields for outgoing partial updates
// ============================================================

#[derive(Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct TransformPatch {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub position: Option<Linear3D>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub rotation: Option<Orientation4D>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub scale: Option<Linear3D>,
}

// ============================================================
// Individual command payloads (3.5 field names)
// ============================================================

fn default_true() -> bool {
    true
}

#[derive(Copy, Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct SetCursorForceCmd {
    pub vector: Force,
    #[serde(default = "default_true")]
    pub execute: bool,
}

#[derive(Copy, Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct SetCursorPositionCmd {
    pub position: Linear3D,
    #[serde(default = "default_true")]
    pub execute: bool,
}

#[derive(Copy, Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct SetAngularTorquesCmd {
    pub torques: Angular3D,
    #[serde(default = "default_true")]
    pub execute: bool,
}

#[derive(Copy, Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct SetAngularPositionCmd {
    pub angles: Angular3D,
    #[serde(default = "default_true")]
    pub execute: bool,
}

#[derive(Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct SetTransformCmd {
    pub transform: TransformPatch,
    #[serde(default = "default_true")]
    pub execute: bool,
}

#[derive(Copy, Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct ProbeCmd {}

#[derive(Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct SetExtensionDataCmd {
    pub extension_data: Vec<i32>,
}

// ============================================================
// Per-tick command structs (all optional, multiple per device per frame)
// ============================================================

#[derive(Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct Inverse3Commands {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub set_cursor_force: Option<SetCursorForceCmd>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub set_cursor_position: Option<SetCursorPositionCmd>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub set_angular_torques: Option<SetAngularTorquesCmd>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub set_angular_position: Option<SetAngularPositionCmd>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub set_transform: Option<SetTransformCmd>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub probe_position: Option<ProbeCmd>,
    // SDF HFX command (per-tick, not repeated by zero-order hold)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sdf: Option<SdfCommand>,
}

#[derive(Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct VerseGripCommands {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub set_transform: Option<SetTransformCmd>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub probe_orientation: Option<ProbeCmd>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub set_extension_data: Option<SetExtensionDataCmd>,
}

// ============================================================
// One-shot configure structs
// ============================================================

#[derive(Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct PresetConfig {
    pub preset: String,
}

#[derive(Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct MountConfig {
    pub transform: TransformPatch,
}

#[derive(Copy, Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct DampingConfig {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub scalar: Option<f32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub vector: Option<Linear3D>,
}

#[derive(Copy, Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct ForceGateConfig {
    pub gain: f32,
}

// Navigation configure types are in super::navigation, re-exported via mod.rs

#[derive(Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct ProfileConfig {
    pub name: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub required_version: Option<String>,
}

#[derive(Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct Inverse3Configure {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub preset: Option<PresetConfig>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub basis: Option<CoordinateSystem>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub mount: Option<MountConfig>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub damping: Option<DampingConfig>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub force_gate: Option<ForceGateConfig>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub navigation: Option<NavigationConfigure>,
    // SDF output toggle
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sdf: Option<SdfOutputConfigure>,
}

#[derive(Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct VerseGripConfigure {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub preset: Option<PresetConfig>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub basis: Option<CoordinateSystem>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub mount: Option<MountConfig>,
}

#[derive(Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct SessionConfigure {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub profile: Option<ProfileConfig>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub basis: Option<CoordinateSystem>,
}

// ============================================================
// Outgoing device message structs
// ============================================================

#[derive(Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct Inverse3OutMsg {
    pub device_id: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub commands: Option<Inverse3Commands>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub configure: Option<Inverse3Configure>,
}

#[derive(Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct VerseGripOutMsg {
    pub device_id: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub commands: Option<VerseGripCommands>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub configure: Option<VerseGripConfigure>,
}

// ============================================================
// Session message
// ============================================================

#[derive(Copy, Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct ForceRenderFullStateMsg {}

#[derive(Clone, Debug, PartialEq, Default, Deserialize, Serialize, TS)]
pub struct SessionMsg {
    #[serde(skip_serializing_if = "Option::is_none")]
    pub force_render_full_state: Option<ForceRenderFullStateMsg>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub configure: Option<SessionConfigure>,
}

// ============================================================
// Full outgoing service message
// ============================================================

#[derive(Clone, Debug, PartialEq, Deserialize, Serialize, TS)]
pub struct ServiceMsg {
    pub session: SessionMsg,
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub inverse3: Vec<Inverse3OutMsg>,
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub verse_grip: Vec<VerseGripOutMsg>,
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub wireless_verse_grip: Vec<VerseGripOutMsg>,
}

impl Default for ServiceMsg {
    fn default() -> Self {
        ServiceMsg {
            session: SessionMsg {
                force_render_full_state: Some(ForceRenderFullStateMsg {}),
                configure: None,
            },
            inverse3: Vec::new(),
            verse_grip: Vec::new(),
            wireless_verse_grip: Vec::new(),
        }
    }
}

// ============================================================
// High-level command enum for building outgoing frames
// ============================================================

#[derive(Clone, Debug, PartialEq, Deserialize, Serialize, TS)]
pub enum Command {
    // Inverse3 per-tick commands
    SetCursorForce { device_id: String, vector: Force, execute: bool },
    SetCursorPosition { device_id: String, position: Linear3D, execute: bool },
    SetAngularTorques { device_id: String, torques: Angular3D, execute: bool },
    SetAngularPosition { device_id: String, angles: Angular3D, execute: bool },
    SetI3Transform { device_id: String, transform: TransformPatch, execute: bool },
    ProbePosition { device_id: String },
    // VerseGrip per-tick commands
    ProbeOrientation { device_id: String },
    SetExtensionData { device_id: String, extension_data: Vec<i32> },
    SetVgTransform { device_id: String, transform: TransformPatch, execute: bool },
    // SDF HFX commands
    SdfSet { device_id: String, objects: Vec<SdfHfxObject>, from_space: Option<String> },
    SdfUpdate { device_id: String, objects: Vec<SdfHfxObject> },
    SdfRemove { device_id: String, ids: Vec<String> },
    // Configure (one-shot)
    ConfigureInverse3 { device_id: String, config: Inverse3Configure },
    ConfigureVerseGrip { device_id: String, config: VerseGripConfigure },
    ConfigureSession(SessionConfigure),
    ConfigureSdfOutput { device_id: String, state_output: bool },
    // Session-level
    ForceRenderFullState,
    PingService,
}