Task #210
Updated by Sanghoon Lee about 2 months ago
Just as xela_server reads real connected sensor data and serves it over a websocket, the sim_xela_server package will be developed to simulate virtual sensor input and serve it continuously over a websocket for testing and development purposes.
In the first step, sim_xela_server supports four target models:
- uSPa46,
- usrp_dsf (uSPrDS),
- uSPa35 (uSPrHE35),
- XR23AHLCPP (Allegro hand v4 left)
These supported models can be selected as parameters during runtime, using pre-prepared profiles and captured base data for each model.
-------------
!{width:700px}clipboard-202602071712-z5l1j.png!
h1. sim_xela_server : xela_server simulation server
h2. 1. Overview
A ROS 2 node that acts as a WebSocket *server* and repeatedly sends a JSON message using a selected
model reference file from @sim_xela_server/resource/<model>.json@. The node accepts a WebSocket client
connection (e.g., @xela_server2_2f@, @xela_server2_ah@) and applies sinusoidal variations to @integer@ or @calibrated@
values after an initial warm-up period.
h2. 2. Goals
* Provide a repeatable WebSocket test stream to validate @xela_server2_2f@ end-to-end.
* Support selectable model references via a parameter.
* Introduce realistic signal variation after a configurable delay.
h2. 3. Inputs
h3. 3.1 Parameters
* @model_name@ (string, required)
** Example: @uSPa35@, @uSPa46@, @XR23AHLCPP_left@
* @ref_dir@ (string, default: @<pkg_share>/resource@)
* @bind_host@ (string, default: @0.0.0.0@)
* @bind_port@ (int, default: 5000)
* @publish_period_ms@ (int, default: 200)
* @warmup_sec@ (double, default: 5.0)
* @use_calibrated_if_present@ (bool, default: true)
* @integer_xy_range@ (double, default: 1350.0)
* @integer_z_range@ (double, default: 10085.0)
* @calib_xy_range@ (double, default: 0.8)
* @calib_z_range@ (double, default: 14.0)
* @sine_freq_hz@ (double, default: 0.05)
* @sine_phase_step@ (double, default: 0.1)
* @preset@ (string, default: @normal@)
** Uses @replayer_presets.<preset>@ from a params YAML when available.
* @variation_mode@ (string, default: @random@)
** @random@ generates independent x/y/z per sensor within the configured ranges.
** @sine@ uses the sinusoidal variation.
* @random_seed@ (int, default: 0)
** 0 uses a non-deterministic seed.
* @random_global_strength@ (double, default: 0.3)
* @random_local_strength@ (double, default: 0.7)
* @random_temporal_alpha@ (double, default: 0.7)
** 0.0 disables temporal smoothing; closer to 1.0 is smoother.
h2. 4. Behavior
h3. 4.1 Message loading
* Load JSON file: @${ref_dir}/${model_name}.json@.
* If missing or invalid, log error and exit.
h3. 4.2 Publishing
* Listen on @ws://<bind_host>:<bind_port>@.
* When a client connects, send the JSON text at @publish_period_ms@ intervals.
* If the client disconnects, wait for the next connection.
h3. 4.3 Signal variation
* For @warmup_sec@, send unmodified JSON.
* After @warmup_sec@:
** If @variation_mode=random@:
*** If @use_calibrated_if_present=true@ and @calibrated@ exists:
**** Random variation uses global + local components per module and temporal smoothing.
**** X/Y within ±0.8 N, Z within 0..14 N around baseline.
*** Else random integer values within:
**** Random variation uses global + local components per module and temporal smoothing.
**** X/Y: baseline ±1350
**** Z: baseline .. baseline+10085
** If @variation_mode=sine@:
*** If @use_calibrated_if_present=true@ and @calibrated@ exists:
**** Apply sine-wave variation to calibrated values.
**** X/Y range: ±0.8 N
**** Z range: 0..14 N
*** Else apply sine-wave variation to integer values:
**** X/Y range: baseline ±1350
**** Z range: baseline .. baseline+10085
* Baseline is the original value in the JSON.
* Each taxel axis uses @sin(2π f t + phase)@ with @phase = idx * sine_phase_step@ when in @sine@ mode.
h2. 5. Output
* WebSocket stream of JSON messages to the connected client.
h2. 6. Constraints
* The node is packaged within @sim_xela_server@ and can run standalone.
* The JSON structure is assumed to match the existing ref files.
h2. 7. Acceptance Criteria
* Node starts, loads JSON, and begins transmitting at configured rate.
* For the first @warmup_sec@, transmitted message matches the reference JSON.
* After warmup, values change sinusoidally within the specified ranges.
* If @calibrated@ exists and enabled, calibrated values change; otherwise integer values change.
h2. 8. Notes
* @temp@ is not modified.
* If calibrated arrays are missing or empty, fallback to integer variation.
-----------------
*README*
h1. sim_xela_server
WebSocket replayer server for Xela taxel JSON data. This package provides a
standalone WebSocket *server* that streams JSON messages to connected clients
(e.g., @xela_server2_ah@, @xela_server2_2f@).
h2. Build
<pre><code class="shell">
source /opt/ros/humble/setup.bash
cd /home/invokelee/xela_robotics/02_dev_ws
colcon build --packages-select sim_xela_server
</code></pre>
h2. Run
<pre><code class="shell">
source /opt/ros/humble/setup.bash
source /home/invokelee/xela_robotics/02_dev_ws/install/setup.bash
ros2 run sim_xela_server sim_xela_server_node --ros-args \
-p model_name:=XR23AHLCPP_left \
-p bind_port:=5000 \
-p integer_z_range:=4000.0 \
-p calib_z_range:=6.0 \
-p z_bias_power:=2.0
</code></pre>
h2. Launch
<pre><code class="shell">
source /opt/ros/humble/setup.bash
source /home/invokelee/xela_robotics/02_dev_ws/install/setup.bash
ros2 launch sim_xela_server sim_xela_server.launch.py \
model_name:=XR23AHLCPP_left \
integer_z_range:=4000.0 calib_z_range:=6.0 z_bias_power:=2.0
</code></pre>
h2. Notes
* Reference JSON files live under @resource/@ in this package.
* Presets are in @config/replayer_presets.yaml@.
* Use @integer_z_range@/@calib_z_range@ to reduce simulated Z amplitude.
* @z_bias_power@ (>1.0) makes small Z values more frequent.
* Presets @H@, @M@, @L@ set @z_bias_power@ to 3.0/2.0/1.2.
* FSD: @fsd_sim_xela_server.md@.
------------
{{video("sim_xela_server_w-xela_viz.mp4",800,400)}}