HyssosTech.Sdk.C2SIM 1.2.8 The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved

.NET 6.0 .NET Standard 2.0
Install-Package HyssosTech.Sdk.C2SIM -Version 1.2.8
dotnet add package HyssosTech.Sdk.C2SIM --version 1.2.8
<PackageReference Include="HyssosTech.Sdk.C2SIM" Version="1.2.8" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add HyssosTech.Sdk.C2SIM --version 1.2.8
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: HyssosTech.Sdk.C2SIM, 1.2.8"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install HyssosTech.Sdk.C2SIM as a Cake Addin
#addin nuget:?package=HyssosTech.Sdk.C2SIM&version=1.2.8

// Install HyssosTech.Sdk.C2SIM as a Cake Tool
#tool nuget:?package=HyssosTech.Sdk.C2SIM&version=1.2.8
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

C2SIM SDK

Resources for controlling state and handling messages in a C2SIM environment. For an overview of C2SIM and its capabilities to support multiple connected Command and Control (C2) and Simulation systems, see the C2SIM Server Reference Implementation Documentation

The focus of the SDK is specifically on the C2SIM protocol, rather than legacy ones (e.g. CBML, IBML, IBML9, MSDL) which may be supported by C2SIM environments as well.

The SDK is built on top of generic capabilities offered by a (ported) Client Library, configured with specific parameters obtained by examining the C2SIM GUI Editor code use of the Java C2SIMClientLib.

In a nutshell, the SDK:

  • Wraps a series of basic Library Commands required to make a C2SIM server transition to a state where it is ready to accept Initializations, or Orders, or to join an ongoing session
  • Issues Library messages with required parameters for pushing specific messages containing Orders, Initializations and Reports
  • Serializes and deserializes XML messages from/into plain old C# objects
  • Exposes generic Library (STOMP) notification messages as finer grained events signaling the reception of Initialization, Orders, Reports, and server status changes

Nuget Install

The HyssosTeck.Sdk.C2SIM nuget provides support for:

  • .NET 6 projects
  • .NET Standard 2.0 - compatible with recent .NET Framework projects

As such, it should be compatible with Windows, macOs and Linux platforms, provided these have the required .NET Runtime/SDK installed

Quick Start

  1. Create a C2SIMSDK object pointing to a C2SIM server

    // ... obtain reference to logger that should be used by the SDK
    ILogger logger = null; // Create an appropriate logger here
    C2SIMSDK c2SimSDK = new C2SIMSDK(
        logger,
        new C2SIMSDKSettings(
            // Id string of this app - use C2SIMSDK.GetMachineID() to get a unique id based on the client hardware
            <submitter id>, 
            // Full C2SIM server endpoint, including host:port/path, e.g. "http://10.2.10.30:8080/C2SIMServer"
            <rest endpoint>, 
            // C2SIM server password
            <rest password>        
            // Full STOMP service endpoint, including host:port/destination, e.g. "http://10.2.10.30:61613/topic/C2SIM"
            <stomp endpoint>, 
            // Protocol - could also be "BML" for example, but the SDK focuses on C2SIM
            "SISO-STD-C2SIM",
            // Version of the protocol - 1.0.0 is the published standard
            "1.0.0"
        )
    );
    

    NOTE: the SDK supports Dependency Injection as part of a .NET Generic Host, which simplifies handling of logging and configuration settings. See the Sample App for an example of how to implement that.

  2. Subscribe to notification events

    c2SimSDK.StatusChangedReceived += C2SimSDK_StatusChangedReceived;
    c2SimSDK.InitializationReceived += C2SimSDK_InitializationReceived;
    c2SimSDK.OderReceived += C2SimSDK_OderReceived;
    c2SimSDK.ReportReceived += C2SimSDK_ReportReceived;
    
  3. Establish the connection to the C2SIM notification service to start the message flow

    try
    {
        // Connect to the notification service to start receiving messages
        await c2SimSDK.Connect();
    }
    catch (Exception e)
    {
        string msg = e.InnerException != null ? e.InnerException.Message : e.Message;
        // Handle error
        // ...
    }
    
  4. Send commands and messages as required

    See the C2SIM .NET SDK Reference for details of the methods summarized below

    1. Change the state of the server
      • ResetToInitializing() - get the server to an Initializing state, issuing STOP, RESET, INITIALIZE individual commands as needed
      • SwitchToRunning() - get the server to a Running state, issuing SHARE, START individual commands as needed
      • JoinSession() - get the server to issue a late join notification, eventually causing an InitializationReceived event to be triggered
    2. Push messages
      • PushInitializationMessage()
      • PushOrderMessage()
      • PushReportMessage()
    3. Access to raw Library functionality
      • PushCommand() C2SIM server commands: STOP, RESET, INITIALIZE, SHARE, START, PAUSE, STATUS, QUERYINIT (see C2SIM Server Message Flow for details) Also supports commands added in v1.0.2 of the schema: RESTART, GETSIMMULT, SETSIMMULT <multiple>, STARTPLAY, STOPPLAY, PAUSEPLAY, GETPLAYSTAT, GETPLAYMULT, SETPLAYMULT <multiple>, STARTREC, STOPREC, PAUSEREC, RESTARTREC, GETRECSTAT, MAGIC <entityUUIDreference> <latitude> <longitude>
      • PushMessage() - client configured XML messages

C2SIM XSD object serialization

The SDK includes classes for schema versions 1.0.0 and 1.0.1. These classes were generated from the Schemas using the xsd tool, distinguished by the namespace - C2SIM.Schema101 or C2SIM.Schema100:

xsd schemas\C2SIM_SMX_LOX_V1.0.1.xsd /c /l:CS /n:C2SIM.Schema101
xsd schemas\C2SIM_SMX_LOX_V1.0.0.xsd /c /l:CS /n:C2SIM.Schema100

A separate augmented C2SIM_SMX_LOX_v1.0.x_Command.xsd is also provided. It includes some elements that are present in the messages sent by the current C2SIM Reference Server (v4.8.1.1), that are not present in the published schemas (either in v1.0.0 or v1.0.1):

  • SystemCommandBodyType includes an additional element - SessionStateCode
  • SystemCommandTypeCodeType includes an additional ResetScenario enumeration

The class for this specific type is then generated by xsd using the following command:

xsd schemas\C2SIM_SMX_LOX_v1.0.0_Command.xsd /c /l:CS /n:C2SIM.CustomSchema

To be able to support toolsets that have not been updated to v1.0.1, the SDK opts to deliver message bodies as XML strings, rather than already serialized object, so that the client app can decide which version to apply

  • Push messages expect XML strings serialized from the following object types:

    • PushInitializationMessage - C2SIMInitializationBodyType
    • PushOrderMessage - OrderBodyType
    • PushReportMessage - ReportBodyType XML containing MessageBody and MessageBody/DomainMessageBody elements wrapping the types above are also accepted by the push methods. If these elements are missing, they are automatically added
  • Notification event handlers are invoked by the SDK with XML representations of the message bodies provided as parameters:

    • StatusChangedReceived - SystemCommandBodyType
    • InitializationReceived - C2SIMInitializationBodyType
    • OderReceived - OrderBodyType
    • ReportReceived - ReportBodyType
    • A generic C2SIMMessageReceived notification is issued for every message. The parameter contains the unparsed content of the received message body. If the Header indicates that the message is C2SIM-compliant (rather than say CBML or other format), then it can be deserialized using a MessageBodyType wrapper type

For convenience, the following utility methods are provided to handle de/serialization:

  • C2SIMSDK.ToC2SIMObject<T>(string xml) - returns an object of type T deserialized from the string parameter
  • C2SIMSDK.FromC2SIMObject<T>(object o) - returns a string with XML serialized from an object of type T

These methods can be used to to handle the desired version of the C2SIM schema by picking the appropriate namespace:

// Serialize a .NET order object into the corresponding C2SIM xml
// If using v1.0.0
string xmlOrder = C2SIMSDK.FromC2SIMObject<C2SIM.Schema100.OrderBodyType>(orderObject);
...
// If using v1.0.1
string xmlOrder = C2SIMSDK.FromC2SIMObject<C2SIM.Schema101.OrderBodyType>(orderObject);
...
// If using either version, SystemCommand requires the use of the CustomSchema
var xmlCommand = C2SIMSDK.FromC2SIMObject<C2SIM.CustomSchema.SystemCommandBodyType>(commandObject);
// Convert received (C2SIM xml) notification body into a .NET object
// If using v1.0.0
var orderObject  = C2SIMSDK.ToC2SIMObject<C2SIM.Schema100.OrderBodyType>(e.Body);
...
// If using v1.0.1
var orderObject = C2SIMSDK.ToC2SIMObject<C2SIM.Schema101.OrderBodyType>(e.Body);
...
// If using either version, SystemCommand requires the use of the CustomSchema
var command = C2SIMSDK.ToC2SIMObject<C2SIM.CustomSchema.SystemCommandBodyType>(e.Body);

Sample app

The methods above are used in a sample app, which accepts commands and messages interactively and sends them to a server. The app also displays notifications received from a server, and can provide insight into the traffic generated by the sample itself or other apps connected to the same server, e.g. the Sketch-Thru-Plan Planning Workstation, as can be seen in this demo.

Product Versions
.NET net5.0 net5.0-windows net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows
.NET Core netcoreapp2.0 netcoreapp2.1 netcoreapp2.2 netcoreapp3.0 netcoreapp3.1
.NET Standard netstandard2.0 netstandard2.1
.NET Framework net461 net462 net463 net47 net471 net472 net48
MonoAndroid monoandroid
MonoMac monomac
MonoTouch monotouch
Tizen tizen40 tizen60
Xamarin.iOS xamarinios
Xamarin.Mac xamarinmac
Xamarin.TVOS xamarintvos
Xamarin.WatchOS xamarinwatchos
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.2.8 54 5/18/2022
1.2.7 70 5/5/2022
1.2.6 69 4/21/2022
1.2.5 120 12/20/2021
1.2.5-prerelease 83 12/6/2021
1.2.4 124 12/3/2021
1.2.4-prerelease 74 12/2/2021
1.2.3 109 11/30/2021
1.2.3-prerelease 74 11/30/2021
1.2.2 108 11/30/2021
1.2.1 3,027 11/24/2021
1.2.0 5,450 11/24/2021
1.2.0-prerelease 4,547 11/24/2021
1.1.0 111 11/23/2021
1.0.0 1,053 11/17/2021
0.9.4-prerelease 107 11/16/2021
0.9.3-prerelease 93 11/16/2021
0.9.2-prerelease 71 11/16/2021
0.9.1-prerelease 86 11/16/2021
0.9.0-prerelease 90 11/16/2021
0.0.4-prerelease 96 11/15/2021
0.0.3-prerelease 109 11/15/2021
0.0.2-prerelease 76 11/15/2021
0.0.1-prerelease 102 11/15/2021

## Version 1.2.8
   * Added a heart-beat option to STOMP connections to enhance the longevity of the subscriptions - defaults to server messages every 10 seconds
   * Refactored the Library settings classes - C2SIMClientRESTSettings and C2SIMClientSTOMPSettings - into separate files
   * Added debug logging listing content of messages and commands

   ## Version 1.2.7
   * Fixed issue with switching connections to another server midrun (connection confirmation got swallowed by previous message pump)
   * Making C2SIMSDK disposable

   ## Version 1.2.6
   * Extended list of commands to comply with the schema version 1.0.2

    ## Version 1.2.5
   * Injecting ILoggerFactory to simplify logger propagation when nested libraries are used
   * Documented Status changed events that signal that the server is waiting for Initialization, or for Orders / Reports

   ## Version 1.2.4
   * Improved reporting on connection error
   * Fixed issue with larger message numbers in C2SIM server response object

   ## Version 1.2.3
   *  More detailed logging
   
   ## Version 1.2.2
   * Fixed issue with server responses, which may sometimes be just strings rather than xml

   ## Version 1.2.1

   * Wrapping Initialization, Order and Report messages in MessageBody if not already present
   * Returning push message server results as strongly typed  objects

   ## Version 1.2.0

   * Changes to make it possible to handle both versions of the schema - v1.0.0 and v1.0.1

   ## Version 1.1.0

   * Updated to C2SIM schema v1.0.1

   ## Version 1.0.0

   * Initial release