Parameterize HapticEvent

dotnet-tools.json → .config/dotnet-tools.json

@@ -3,7 +3,7 @@
   "isRoot": true,
   "tools": {
     "dotnet-reportgenerator-globaltool": {
-      "version": "5.3.6",
+      "version": "5.4.3",
       "commands": [
         "reportgenerator"
       ]

.github/workflows/ci.yaml

@@ -9,8 +9,7 @@ on:
       - '**/ci.yaml'
       - '**/xunit.runner.json'
     branches:
-      - main
-      - '**release**'   # Trigger on branches with 'release' in the name
+      - '**'            # Trigger on all branches
   pull_request:
     paths:              # Trigger when source code, sln or prj files, this file, or the xunit config file is changed.
       - '**/*.cs'
@@ -42,7 +41,7 @@ jobs:
       - name: Setup .NET Core
         uses: actions/setup-dotnet@v4
         with:
-          dotnet-version: '7.x' # Adjust to your target .NET version
+          dotnet-version: '9.x' # Adjust to your target .NET version
 
       # Uncomment this process if you want the windows build to take 3mins extra but get rid of the 'Workload updates are available. Run `dotnet workload list` for more information' msg after building
       #- name: Update dotnet workloads (Windows)
@@ -55,15 +54,15 @@ jobs:
       - name: Build solution without restore
         run: dotnet build tests/EStimLibrary.UnitTests/EStimLibrary.UnitTests.sln --no-restore --configuration Release
 
-      - name: Install ReportGenerator
-        run: dotnet tool install -g dotnet-reportgenerator-globaltool
+      - name: Restore .NET Tools
+        run: dotnet tool restore
 
       - name: Run unit tests and collect coverage
         run: dotnet test tests/EStimLibrary.UnitTests/EStimLibrary.UnitTests.csproj --no-build --configuration Release --collect:"XPlat Code Coverage"
 
       - name: Generate coverage report
         run: |
-          reportgenerator -reports:tests/**/coverage.cobertura.xml -targetdir:coverage -reporttypes:Html
+          dotnet tool run reportgenerator -reports:tests/**/coverage.cobertura.xml -targetdir:coverage -reporttypes:Html
 
       - name: Upload coverage report
         uses: actions/upload-artifact@v4

.github/workflows/release.yaml

@@ -24,7 +24,7 @@ jobs:
       - name: Setup .NET Core
         uses: actions/setup-dotnet@v4
         with:
-          dotnet-version: '7.x' # Adjust to your target .NET version
+          dotnet-version: '9.x' # Adjust to your target .NET version
 
       - name: Restore dependencies
         run: dotnet restore $SLN_PATH

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "_comment1": "specify which solution to load for C# Dev Kit tooling. Switch if working on a different sln",
+    "_comment2": "examples/EStimLibrary.ConsoleAppDemo/EStimLibrary.ConsoleAppDemo.sln",
+    "dotrush.roslyn.projectOrSolutionFiles": [
+        "tests/EStimLibrary.UnitTests/EStimLibrary.UnitTests.sln"
+    ]
+}

README.md

@@ -1,19 +1,90 @@
 # EStimLibrary
 A C# library to facilitate electrical stimulation research and development.
 
-More details coming soon.
+## Table of Contents
+* [Dependencies](#dependencies)
+    * [Extensions for VSCode Users](#extensions-for-vscode-users)
+* [Repo Contents](#repo-contents)
+    * [Top-Level Structures](#top-level-structure)
+    * [Projects and Solutions](#projects-and-solutions)
+* [Library Structure](#library-structure)
+* [Diagrams](#diagrams)
+* [Usage](#usage)
+    * [VisualStudio](#visualstudio)
+    * [VSCode or your other preferred IDE](#vscode-or-your-other-preferred-ide)
 
-## Repo Structure
-* `src/` - the library source code
-* `tests/` - the test projects
+## Dependencies
+* .NET 9.0
+    * 10-minute [Tim Corey video](https://www.youtube.com/watch?v=sXEsvqCCTTc): how to upgrade or install fresh
+    * Windows: Use VisualStudio
+    * MacOS, Linux: download and install manually to access `dotnet` command-line interface (CLI)
+* `nuget` packages:
+    * For base library:
+        * System.IO.Ports
+        * MathNet.Numerics
+        * Newtonsoft.Json
+    * For xUnit testing project:
+        * Microsoft.NET.Test.Sdk
+        * xunit
+        * xunit.runner.visualstudio
+        * xunit.runner.console
+        * coverlet.collector
+    * Versions are listed in the `.csproj` files and should be pulled automatically when building projects and solutions in this repo.
+
+### Extensions for VSCode Users
+Optional but highly recommended:
+* C# Dev Kit: provides much of the same C# support and within-solution navigation features as VisualStudio
+
+## Repo Contents
+### Top-Level Structure
+* `src/` - the library source code project
+* `tests/` - the test project(s)
 * `models/` - examples of spatial model definition files
-* `examples/` - example applications using the library's high-level API
+    * contains [`EStimLibrary.SpatialModels`](https://github.com/lhmcgann/EStimLibrary.SpatialModels/) as a submodule
+* `examples/` - example applications (projects) using the library's high-level API
 * `docs/` - additional documentation files, including a dictionary and coding conventions
 
-## UML Diagrams
-Last updated: March 2024
-* [Class Diagram](https://lucid.app/lucidchart/298700bf-4e2e-4c7d-bb06-76365f1efb98/edit?viewport_loc=-7329%2C-1594%2C17982%2C8602%2C0_0&invitationId=inv_11b76774-377e-4967-87a5-c173614a4ef3)
-* [Sequence and Use Case Diagrams](https://lucid.app/lucidchart/e774e654-27e9-4168-aee4-39f6f8133738/edit?viewport_loc=-403%2C-342%2C1628%2C779%2C0_0&invitationId=inv_cb3b6cf3-cb84-4091-bd72-88547d50cb3e)
+### Projects and Solutions
+There are currently 3 projects in this repo:
+1. `src/EStimLibrary/EStimLibrary.csproj`: the base library project itself
+    * Builds into a `.dll`
+2. `tests/EStimLibrary.UnitTests/EStimLibrary.UnitTests.csproj`: the xUnit test project
+    * The unit tests for the library
+3. `examples/EStimLibrary.ConsoleAppDemo/EStimLibrary.ConsoleAppDemo.csproj`: an example console app project that either runs through a hard-coded session config and execution, or walks through the config step-by-step, asking for user input at each step
+    * Highlights the `Utils` reflection capabilities,
+    * and exemplifies the major `HapticSession` config components.
+
+There are 3 corresponding solutions in this repo:
+1. `EStimLibrary.sln`: builds only the base library project
+2. `tests/EStimLibrary.UnitTests/EStimLibrary.UnitTests.sln`: builds the base library and the xUnit test projects
+3. `examples/EStimLibrary.ConsoleAppDemo/EStimLibrary.ConsoleAppDemo.sln`: builds the base library and the example console app projects
+
+## Library Structure
+The main library, in `src/EStimLibrary/`, is broken down into two top-level folders:
+* `Core/`: the base declarations and implementatsions of interfaces, abstract classes, and core classes
+* `Extensions/`: provided implementations of some core interfaces and abstract classes that are commonly used
+
+The `Core/` folder contains the following structure:
+* `Data/`: primarily `IDataLimits`
+* `Haptics/`: classes on the haptic event side of the pipeline, e.g., `HapticSession`, `HapticEvent`, and `HapticTransducer`
+* `HardwareInterfaces/`: leads, cables, neural interfaces
+* `SpatialModel/`: location, area, body model, and related content
+* `Stimulation/`: stimulators and stimulation representations
+* Miscellaneous infrastructure interfaces and classes are in the top level of the `Core/` folder, e.g., `Utils`, `ResourceManager`, `ReusableIdPool`
+
+The `Extensions/` folder mimics this structure to the extent that example implementations are provided.
+
+The `EStimLibrary.UnitTests` project also mimics the `Core/`, `Extensions/`, and sub-directory structures.
+
+## Diagrams
+Last updated: February 2025
+
+These diagrams are based on UML formatting but adhere to that to varying degrees.
+* [Key Components](https://lucid.app/lucidchart/7b9b75ff-8dee-41d8-b650-082adc9bcb8f/edit?viewport_loc=-1212%2C-695%2C5508%2C2636%2C0_0&invitationId=inv_0a3eaaf0-7a4f-4fcd-a813-b786f47e548f)
+* [Class Diagram - High-Level](https://lucid.app/lucidchart/1366a885-086c-45d0-8763-63448fe11a86/edit?viewport_loc=-3539%2C-4330%2C16143%2C7727%2C0_0&invitationId=inv_10ca78f7-8fcc-4d34-8466-aa8da86d8716)
+* [`StringHierarchy` Class Diagram](https://lucid.app/lucidchart/8f0c6f70-c343-444e-9e6f-5c51557384ec/edit?viewport_loc=-2888%2C-1102%2C7382%2C3534%2C0_0&invitationId=inv_7e104f4d-b695-4ff7-84b2-87b3bff9a9fb)
+* [Sequence Diagrams](https://lucid.app/lucidchart/312bfb4e-807b-4f90-9e56-7cdc64a0172d/edit?viewport_loc=-858%2C313%2C2104%2C917%2C0_0&invitationId=inv_94e9dfe8-1656-45c9-abc7-d433c77d7a95)
+* [Use Case Diagrams](https://lucid.app/lucidchart/85097f76-39d7-49a4-b1a6-5fa749e0ad9f/edit?viewport_loc=-3588%2C-303%2C10396%2C4532%2C0_0&invitationId=inv_c1be5bbe-3b3e-4b08-b021-a66debdfbed8)
 
 Beneficial in the future:
 * package diagram showing the interface exposed to the public
@@ -23,3 +94,27 @@ Beneficial in the future:
 
 See [UML.md](./docs/UML.md) for a UML intro.
 
+
+## Usage
+To use the library, clone the repo and checkout the `release-v2.0` branch for the most recent development:
+```
+# To clone submodules as well: call git clone with the --recurse-submodules option if you have Git 2.13 or later, else --recursive
+git clone git@github.com:lhmcgann/EStimLibrary.git
+cd EStimLibrary
+git checkout release-v2.0
+```
+
+### VisualStudio
+1. Open the `.sln` file corresponding to the projects you want to open. 
+2. Press the "play" button in the top left to build (and run, if applicable) the loaded solution.
+3. To run the test project, click the green "play" button in Test Explorer.
+
+### VSCode or your other preferred IDE
+1. Open the `EStimLibrary/` folder in your workspace.
+2. In Terminal, navigate to the folder with the desired project or solution.
+3. Use `dotnet` CLI commands. See a cheatsheet [here](https://www.lostindetails.com/articles/dotnet-cheatsheet).
+    1. `dotnet build` to build any project
+    2. `dotnet run` to run the example console app
+    3. `dotnet test` to run the xUnit test suite
+
+

examples/EStimLibrary.ConsoleAppDemo/EStimLibrary.ConsoleAppDemo.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net7.0</TargetFramework>
+    <TargetFramework>net9.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
   </PropertyGroup>

examples/EStimLibrary.ConsoleAppDemo/Program.cs

@@ -660,12 +660,14 @@
                         "left hand, index finger, distal phalanx | palmar");
     foreach (var pVal in pressureValues)
     {
-        var pNormVec = Vector<double>.Build.Dense(new double[] { pVal });
+        //var pNormVec = Vector<double>.Build.Dense(new double[] { pVal });
+        var hapticParams = new Dictionary<HapticParam, double>();
+        hapticParams.Add(HapticParam.P, pVal);
         var event1 = new HapticEvent(DateTime.Now, null,
             new() {
                 { "left hand", new List<IArea>() { eventArea1 } }//, eventArea2 } }
             },
-            pNormVec);
+            hapticParams);
         session.AddEvent(event1);
     }
     session.Stop();

src/EStimLibrary/Core/Data/IDataLimits.cs

@@ -0,0 +1,28 @@
+namespace EStimLibrary.Core.Data;
+
+
+/// <summary>
+/// A structure to represent the limits on a specific associated parameter or
+/// other data value, supplying data type information and bounding/limiting
+/// validation.
+/// </summary>
+public interface IDataLimits : ISelectable
+{
+    /// <summary>
+    /// The data type that is valid for the associated data.
+    /// </summary>
+    public Type ValidDataType { get; }
+    /// <summary>
+    /// A strign description of the limits this structure imposes on the
+    /// associated data. Meant to be open-ended to accommodate listing discrete
+    /// options, explaining bounds, etc. Basically a 'help' message.
+    /// </summary>
+    public string Description { get; }
+    /// <summary>
+    /// Validate a specific data value. Must be non-null and of the
+    /// ValidDataType, in addition to any other validation checks.
+    /// </summary>
+    /// <param name="value"></param>
+    /// <returns>True if the value is valid, false if not.</returns>
+    bool IsValidDataValue(object value);
+}