From bbf98fc1acfcdc5c2d3aff8532fce508291d5a2a Mon Sep 17 00:00:00 2001 From: Mamadou Babaei Date: Fri, 10 Jul 2026 19:19:41 +0200 Subject: [PATCH] add the fakeshm module tuning utilities and ininitial draft of its documentation and its third-party dependencies licenses --- .gitattributes | 6 + Handbook/src/SUMMARY.md | 1 + Handbook/src/appendix/changelog.md | 2 + .../sensecom/fakeshm-tuning/README.md | 135 ++++++++++++++++++ .../argh-command-line-processing-library.md | 30 ++++ .../license/ftxui-functional-tui-library.md | 25 ++++ Handbook/src/license/third-party.md | 4 + Handbook/src/overview/README.md | 1 + Packager/sgum-packager.yml | 1 + Tuning/README.md | 5 + Tuning/sgfakeshm-connect-client | 3 + Tuning/sgfakeshm-connect-client.exe | 3 + Tuning/sgfakeshm-core-client | 3 + Tuning/sgfakeshm-core-client.exe | 3 + 14 files changed, 222 insertions(+) create mode 100644 Handbook/src/getting-started/sensecom/fakeshm-tuning/README.md create mode 100644 Handbook/src/license/argh-command-line-processing-library.md create mode 100644 Handbook/src/license/ftxui-functional-tui-library.md create mode 100644 Tuning/README.md create mode 100755 Tuning/sgfakeshm-connect-client create mode 100755 Tuning/sgfakeshm-connect-client.exe create mode 100755 Tuning/sgfakeshm-core-client create mode 100755 Tuning/sgfakeshm-core-client.exe diff --git a/.gitattributes b/.gitattributes index 9d83b32c..28ca9562 100644 --- a/.gitattributes +++ b/.gitattributes @@ -50,3 +50,9 @@ Handbook/dist/**/* filter=lfs diff=lfs merge=lfs -text # LFS: sgum-packager Linux and Windows binaries Packager/sgum-packager filter=lfs diff=lfs merge=lfs -text Packager/sgum-packager.exe filter=lfs diff=lfs merge=lfs -text + +# LFS: sgfakeshm-connect-client abd sgfakeshm-core-client Linux and Windows binaries +Tuning/sgfakeshm-connect-client filter=lfs diff=lfs merge=lfs -text +Tuning/sgfakeshm-connect-client.exe filter=lfs diff=lfs merge=lfs -text +Tuning/sgfakeshm-core-client filter=lfs diff=lfs merge=lfs -text +Tuning/sgfakeshm-core-client.exe filter=lfs diff=lfs merge=lfs -text \ No newline at end of file diff --git a/Handbook/src/SUMMARY.md b/Handbook/src/SUMMARY.md index 52d6e03b..5dbb6bba 100644 --- a/Handbook/src/SUMMARY.md +++ b/Handbook/src/SUMMARY.md @@ -25,6 +25,7 @@ Welcom to the SenseGlove Unreal Engine Handbook! - [Connect to Nova gloves using Blueman Bluetooth Manager](getting-started/sensecom/bluetooth-serial/gnu-linux/blueman-bluetooth-manager.md) - [Connect to Nova gloves using Command-line](getting-started/sensecom/bluetooth-serial/gnu-linux/command-line.md) - [SenseCom on Microsoft Windows](getting-started/sensecom/bluetooth-serial/microsoft-windows.md) + - [FakeShm Module Tuning](getting-started/sensecom/fakeshm-tuning/README.md) - [Enabling XR_EXT_hand_tracking on VR Headsets](getting-started/enabling-xr-ext-hand-tracking-vr-headsets/README.md) - [PCVR Mode](getting-started/enabling-xr-ext-hand-tracking-vr-headsets/pcvr-mode/README.md) - [Standalone Mode](getting-started/enabling-xr-ext-hand-tracking-vr-headsets/standalone-mode/README.md) diff --git a/Handbook/src/appendix/changelog.md b/Handbook/src/appendix/changelog.md index d755e2ab..e14f0e0c 100644 --- a/Handbook/src/appendix/changelog.md +++ b/Handbook/src/appendix/changelog.md @@ -25,6 +25,7 @@ This minor release introduces a major IPC overhaul, significant inter-process co - Added `SGBuildHacks/SGInclude_Core_DeviceTypes`. - Added missing `ESGBackendType::AndroidStrings` enumerator. - Added missing SenseGlove API Blueprint function `USGLibraryKismetLibrary::GetBackendType()`. +- Added the [Microsoft Windows and GNU/Linux binary distribution of **SenseGlove FakeShm Module Tuning Utilities**](https://dev.azure.com/SenseGlove/_git/SenseGlove-Unreal?path=/Tuning&version=GBmaster&_a=contents) to the SenseGlove Unreal Engine Plugin repository on Microsoft Azure repositories. These binaries are not part of the [official plugin release via the Fab Store](https://www.fab.com/listings/62bcdd2a-0bb1-4f34-b7b8-c5e7c9313099). ### Fixed @@ -80,6 +81,7 @@ This minor release introduces a major IPC overhaul, significant inter-process co ### Documentation +- Added the [SenseCom > FakeShm Module Tuning](../getting-started/sensecom/fakeshm-tuning/) documentation section. - Added [The c4core C++ Library Licence](../license/c4core-library.html) section. - Added [The c4project CMake Scripts Licence](../license/c4project-cmake-scripts.html) section. - Added [The Debug Break Library Licence](../license/debugbreak-library.html) section. diff --git a/Handbook/src/getting-started/sensecom/fakeshm-tuning/README.md b/Handbook/src/getting-started/sensecom/fakeshm-tuning/README.md new file mode 100644 index 00000000..19482735 --- /dev/null +++ b/Handbook/src/getting-started/sensecom/fakeshm-tuning/README.md @@ -0,0 +1,135 @@ +# SenseGlove FakeShm Module Tuning + +```yaml +# File name used for tweaking and tuning the FakeShm parameters. +# When this file does not exist it will be generated by the SGConnectShm upon +# initialization or reconfiguration and gets populated from the hardcoded values +# below. +# If it does indeed exist and file version matches the version supported by the +# current release of the SenseGlove libraries, the parameters values in this +# file will override the hardcoded values from the libraries. +# If the file has invalid values, or the version number does not match, it will +# be renamed to sgfakeshm-params.yml.YYYY-MM-DD-hh-mm-ss to +# preserve the user's choosen values and a new file will be generated containing +# the updated values or newly introduced parameters. +# +# NOTE: This file supports hot-reloading upon saving the file. Thus, you do +# not have to close SenseCom or plugin's relying on SenseGlove libraries in +# order to apply the changes. The changes will be picked up automatically +# as soon as a file change is detected. + +# The current version of the the default tuning parameters configuration +# file. +# +# Existing tuning configuration files are only loaded when their version +# matches the version supported by the current FakeShm implementation. +# Otherwise, the existing file is backed up with a timestamped filename +# and a new file containing the current default parameters is generated. +# +# Please do not change this value if you want your changes to persist. +Version: 1 + +# If enabled, socket receive operations are performed in non-blocking +# mode. +# nng_recvmsg will return immediately if no message is available: +# - NNG_EAGAIN is returned instead of blocking +# This improves responsiveness but may increase CPU usage due to +# polling. +# When disabled, SocketReceiveTimeout controls blocking behavior. +SocketReceiveNonBlocking: true + +# Receive timeout for the NNG socket in milliseconds. +# Controls how long nng_recvmsg blocks while waiting for a message. +# If no message is received within this interval, the call returns +# with a timeout, allowing the worker thread to wake up periodically +# to: +# - send heartbeats +# - detect peer liveness +# - respond to shutdown requests +# Lower values increase responsiveness but may slightly increase CPU +# usage. +# This only is taken into account when SocketReceiveNonBlocking is +# disabled. +SocketReceiveTimeout: 1 + +# If enabled, socket send operations are performed in non-blocking +# mode. +# nng_sendmsg will return immediately if the message cannot be sent: +# - NNG_EAGAIN is returned instead of blocking +# Useful for low-latency systems where blocking is undesirable. +SocketSendNonBlocking: false + +# Send timeout for the NNG socket in milliseconds. +# Controls how long nng_sendmsg blocks while attempting to send a +# message. +# If the message cannot be sent within this interval, the call returns +# with a timeout error, allowing the system to avoid long blocking +# stalls. +# This only is taken into account when SocketSendNonBlocking is +# disabled. +SocketSendTimeout: 1 + +# This is the minimum amount of time (milliseconds) to wait before +# attempting to establish a connection after a previous attempt has +# failed. This can be set on a socket, but it can also be overridden +# on an individual dialer. The option is irrelevant for listeners. +SocketReconnectTimeMin: 1 + +# This is the maximum amount of time (milliseconds) to wait before +# attempting to establish a connection after a previous attempt has +# failed. If this is non-zero, then the time between successive +# connection attempts will start at the value of +# SocketReconnectTimeMin, and grow exponentially, until it reaches +# this value. If this value is zero, then no exponential back-off +# between connection attempts is done, and each attempt will wait the +# time specified by SocketReconnectTimeMin. This can be set on a +# socket, but it can also be overridden on an individual dialer. The +# option is irrelevant for listeners. +SocketReconnectTimeMax: 10 + +# FakeShm transport worker retry interval in milliseconds. +# Applied when: +# - no peer is connected +# - socket returns no data (timeout / EAGAIN) +# Prevents busy-waiting loops and reduces CPU usage while idle. +WorkerRetryInterval: 1 + +# FakeShm transport heartbeat interval in milliseconds. +# Determines how often heartbeat messages are sent to the peer to: +# - maintain connection activity +# - update last-seen timestamps +# Lower values improve liveness detection but increase traffic +# overhead. +HeartbeatInterval: 1 + +# FakeShm IPC and TCP transports liveness timeout in milliseconds. +# Defines how long a peer can remain silent before being considered +# dead. +# Compared against the timestamp of the last received message. +# If exceeded, the peer is treated as disconnected/unresponsive. +LivenessTimeout: 5 + +# Latency smoothing window in milliseconds. +# Defines the time range over which latency samples are accumulated +# to compute a rolling average (smoothed latency). +# Larger values produce more stable results but react slower to +# changes. +LatencySmoothingWindow: 1000 + +# Throughput smoothing window in milliseconds. +# Defines the time range over which throughput snapshots are +# accumulated to compute a rolling average (smoothed snapshots). +# Larger values produce more stable results but react slower to +# changes. +ThroughputSmoothingWindow: 1000 + +# The legacy Boost SharedMem heartbeat block size. +SharedMemHeartbeatBlockSize: 1024 + +# FakeShm SharedMem liveness timeout in milliseconds. +# Defines how long a peer can remain silent before being considered +# dead. +# Compared against the timestamp of the last received message. +# If exceeded, the peer is treated as disconnected/unresponsive. +SharedMemLivenessTimeout: 50 +``` diff --git a/Handbook/src/license/argh-command-line-processing-library.md b/Handbook/src/license/argh-command-line-processing-library.md new file mode 100644 index 00000000..97cdf604 --- /dev/null +++ b/Handbook/src/license/argh-command-line-processing-library.md @@ -0,0 +1,30 @@ +# The Argh Frustration-free Command-line Processing Library Licence + +``` +Copyright (c) 2016, Adi Shavit +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + * Neither the name of nor the names of its contributors may be used to + endorse or promote products derived from this software without specific + prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. +``` diff --git a/Handbook/src/license/ftxui-functional-tui-library.md b/Handbook/src/license/ftxui-functional-tui-library.md new file mode 100644 index 00000000..98be4756 --- /dev/null +++ b/Handbook/src/license/ftxui-functional-tui-library.md @@ -0,0 +1,25 @@ +# The FTXUI Functional Terminal (X) User Interface Library Licence + +``` +The MIT License + +Copyright (c) 2019 Arthur Sonzogni. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. +``` diff --git a/Handbook/src/license/third-party.md b/Handbook/src/license/third-party.md index 80165c75..c32b6f1d 100644 --- a/Handbook/src/license/third-party.md +++ b/Handbook/src/license/third-party.md @@ -6,6 +6,7 @@ The following third-party software are used and shipped with the SenseGlove Unre - [The SenseGlove SDK (a.k.a. SenseGlove Backend Libraries, or SenseGlove Core Libraries)](senseglove-sdk.md) - [SGBLE and SGBLExx Rust Dependencies](sgble-sgblexx-rust-dependencies.md) +- [The Argh Frustration-free Command-line Processing Library](argh-command-line-processing-library.md) - [The Boost C++ Libraries](boost-cpp-libraries.md) - [The c4core C++ Library](c4core-library.md) - [The c4project CMake Scripts](c4project-cmake-scripts.md) @@ -13,9 +14,12 @@ The following third-party software are used and shipped with the SenseGlove Unre - [The fast_float Number Parsing Library](fast-float-number-parsing-library.md) - [The FlatBuffers Memory Efficient Serialization Library](flatbuffers-serialization-library.md) - [The {fmt} Formatting Library](fmt-formatting-library.md) +- [The FTXUI Functional Terminal (X) User Interface Library](ftxui-functional-tui-library.md) - [The Loguru Logging Library](loguru-logging-library.md) - [The nanomsg-next-generation Lightweight Brokerless Messaging Library](nng-messaging-library.md) - [The Rapid YAML Parsing and Emitting Library](rapidyaml-parsing-emitting-library.md) - [The Serial Communication Library](serial-communication-library.md) +__NOTE__: **FTXUI** and **Argh** are only used by [the SenseGlove FakeShm Module Tuning Utilities, `sgfakeshm-connect-client` and `sgfakeshm-core-client`](https://dev.azure.com/SenseGlove/_git/SenseGlove-Unreal?path=/Tuning&version=GBmaster&_a=contents) distributed as separate binaries via [the SenseGlove Unreal Engine Plugin Microsoft Azure DevOps repository](https://dev.azure.com/SenseGlove/_git/SenseGlove-Unreal). Since these utilities are not part of [the official release of the SenseGlove Unreal Engine Plugin via the Fab Store](https://www.fab.com/listings/62bcdd2a-0bb1-4f34-b7b8-c5e7c9313099), their respective licensing terms won't apply to the SenseGlove SDK or the UE plugin. + For more information consult their own respective open-source licenses, please. diff --git a/Handbook/src/overview/README.md b/Handbook/src/overview/README.md index e8ba37dd..8cf6a26c 100644 --- a/Handbook/src/overview/README.md +++ b/Handbook/src/overview/README.md @@ -21,6 +21,7 @@ This section covers the basics of the SenseGlove Unreal Engine Plugin: - [Connect to Nova gloves using Blueman Bluetooth Manager](../getting-started/sensecom/bluetooth-serial/gnu-linux/blueman-bluetooth-manager.md) - [Connect to Nova gloves using Command-line](../getting-started/sensecom/bluetooth-serial/gnu-linux/command-line.md) - [SenseCom on Microsoft Windows](../getting-started/sensecom/bluetooth-serial/microsoft-windows.md) + - [FakeShm Module Tuning](../getting-started/sensecom/fakeshm-tuning/) - [Enabling XR_EXT_hand_tracking on VR Headsets](../getting-started/enabling-xr-ext-hand-tracking-vr-headsets/) - [PCVR Mode](../getting-started/enabling-xr-ext-hand-tracking-vr-headsets/pcvr-mode/) - [Standalone Mode](../getting-started/enabling-xr-ext-hand-tracking-vr-headsets/standalone-mode/) diff --git a/Packager/sgum-packager.yml b/Packager/sgum-packager.yml index fc2d4200..fa87af85 100644 --- a/Packager/sgum-packager.yml +++ b/Packager/sgum-packager.yml @@ -57,6 +57,7 @@ Deploy: - Handbook - Packager - README.md + - Tuning Git: diff --git a/Tuning/README.md b/Tuning/README.md new file mode 100644 index 00000000..6ef28354 --- /dev/null +++ b/Tuning/README.md @@ -0,0 +1,5 @@ +# SenseGlove FakeShm Module Tuning Utilities + +The `sgfakeshm-connect-client` and `sgfakeshm-core-client` benchmarking and tuning utilities are only distributed via [the SenseGlove Unreal Engine Plugin Microsoft Azure DevOps repository](https://dev.azure.com/SenseGlove/_git/SenseGlove-Unreal) and is not part of [the official release on the Fab Store](https://www.fab.com/listings/62bcdd2a-0bb1-4f34-b7b8-c5e7c9313099). + +Pleasee see the [relevant documentation section](../Handbook/src/getting-started/sensecom/fakeshm-tuning/README.md) and [licensing terms](../Handbook/src/license/third-party.md) for more information. diff --git a/Tuning/sgfakeshm-connect-client b/Tuning/sgfakeshm-connect-client new file mode 100755 index 00000000..5105f438 --- /dev/null +++ b/Tuning/sgfakeshm-connect-client @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:53f838052bcf5127ae27b9583fd4dcdb1e04517a38078ae5305ffe3dbc3e47d3 +size 1598048 diff --git a/Tuning/sgfakeshm-connect-client.exe b/Tuning/sgfakeshm-connect-client.exe new file mode 100755 index 00000000..a15c1487 --- /dev/null +++ b/Tuning/sgfakeshm-connect-client.exe @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:924d29ceabdce0aa1286a1cdc3123e888ff610053302c1ebf7cc07dfb138f6af +size 1193472 diff --git a/Tuning/sgfakeshm-core-client b/Tuning/sgfakeshm-core-client new file mode 100755 index 00000000..25c8cfba --- /dev/null +++ b/Tuning/sgfakeshm-core-client @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:56bb67f0c3df66eb8ab11bfae0db97b69e0a6f7a0bf48708943c629fdc4e7e66 +size 1566672 diff --git a/Tuning/sgfakeshm-core-client.exe b/Tuning/sgfakeshm-core-client.exe new file mode 100755 index 00000000..6d9b00b0 --- /dev/null +++ b/Tuning/sgfakeshm-core-client.exe @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d0cef4dba989ac9c92a69d8532b708d37b949442448e970601e25b1a10ad5fc7 +size 1140736