About This project

This project is an unofficial community provided client software development kit for IHC (Intelligent House Concept) with clients running Microsoft .NET on Windows, Mac and Linux variants (incl. raspberry pi).

This project is released as open source. Please supply pull requests with tested changes. New contributors are welcome!

NOTE: Before running any tests, tools or examples in this repo, please create and configure a private ihcsettings.json file with information on your IHC installation. Refer to the ihcsettings_template.json for details on what is needed. While the file is needed for tests/tools/examples located here, the file is NOT needed in your own projects if you simply consume this SDK. Finally, you also need to enable network access and thirdparty access in the IHC administrator interface app from LK.

Important disclaimers:

• Please notice that this project is not in any way affiliated with- or supported by LK / Schneider Electric. It exist only because Schneider Electric has not yet released a public SDK themselves.
• The project is unofficial, unfinished and may contain serious bugs. Use at your own risk!
• The project is only partially supported. You are welcome to report bugs and feature requests but don't expect quick solutions unless you supply tested pull-requests as well (or offer to pay the author(s) for support).
• The project is intended for experienced .NET developers using C# and/or F#.
• The IHC has been tested against v3.0 controllers using both Mac and Windows (but Linux ought to work too). More testing from users are needed. Feedback is welcome.

Status

The project is an early preview/beta.

The SDK currently supports v3.0 IHC controller's only. Support with pre-3.0 controllers is possible but require contributors interested in this. See this Issue to discuss this subject and to keep track of future support.

Definitely missing is an easy to consume nuget package for the client. I expect to publish a package if there is interest. For now you will have to build the client yourself.

See here ihcclient for more details on IHC API implementation status.

Content

This project is hosted in a mono-repo containing the following sub-projects:

• SDK:
  • ihcclient This is the main project that contains the code for the IHC client API. This is the project you will need to reference in your own solutions.
• SDK usage examples:
  • ihcclient_example1 contains code for simple command line client console program in c#. Use this for inspiration on how to get started.
  • ihcclient_example2 contains code for simple command line client console program in c#. Use this for inspiration on how to get started.
• SDK utilities:
  • Ihc Lab contains an experimental cross-platform GUI for calling individual API's.
  • Program code extractor contains an optional command line utility for software developers that can generate constant definitions of IO addresses in a concrete IHC installation. Use this approach in your projects if you don't want to lookup and hardcode IO addresses yourself.
  • IHC Http Proxy recorder contains a simple http proxy useful for software (sdk) developers to investigate undocumented IHC controller API's.
  • IHC Project download/upload contains a tool to download/upload project files.
  • IHC Settings encrypt contains a tool to encrypt/decrypt passwords in ihcsettings.json.
• SDK tests:
  • Safe Lab tests contains headless gui tests for Ihc Lab utility. Does not access a controller.
  • Safe integration tests contains system integration tests written in c# that can be safely run aginst a controller in use.
  • Safe unit tests contains unit tests written in c# that does not access a controller.

Configuration

The SDK use a ihc_settings.json file to configure IHC controller, logging/telemetry, application setup and tests. Before using the SDK or any utilties/tests/examples take a copy the ihcsettings_template.json into ihcsettings.json in the same directory and fill-in the details of your installation such as endpoint, username, password etc. See also ihcsettings_example.json.

"ihcclient": {
        "endpoint" : "http://192.100.1.10",
        "userName" : "johndoe",
        "password" : "mypassword",
        "application" : "administrator",
        "logSensitiveData": false,
        "asyncContinueOnCapturedContext": false
},

Note:

• Endpoint should be the http/https baseurl for the controller. If connecting to controller over usb, use endpoint set to "http://usb".
• Username and password should match user setup by controller. Ignored by controller if logging in over usb.
• Application name is can be set to 'treeview', 'openapi', 'administrator'".
• Keep logSensitiveData and asyncContinueOnCapturedContext set to false unless you know what you are doing.

Secure password in configuration

For better security, you can encrypt the password stored in ihcsettings.json instead of keeping it in plaintext. The SDK provides an encryption utility and automatically decrypts passwords at runtime when configured correctly.

Using the IHC Settings Encrypt Utility

The IHC Settings Encrypt utility allows you to encrypt and decrypt passwords in your configuration file using AES-256-GCM encryption.

Quick Start:

1. Set your encryption passphrase (12+ characters, keep it secure) in a system enviroment variable:

   export IHC_ENCRYPT_PASSPHRASE="your-secure-passphrase-here"

2. Encrypt your password:

   dotnet run --project utilities/ihc_settings_encrypt/ihc_settings_encrypt.csproj -- encrypt ihcsettings.json

3. Your ihcsettings.json will be updated with the encrypted password and encryption.isEncrypted set to true:

   {
     "encryption": {
       "isEncrypted": true
     },
     "ihcclient": {
       "endpoint": "http://192.168.1.100",
       "userName": "johndoe",
       "password": "AUk7A8St5R3czttCtvdE2un-WCO0g49...",
       "application": "administrator"
     }
   }

4. The SDK will automatically decrypt the password when isEncrypted is set to true when using the build-in methods IhcSettings.GetFromConfiguration() or IhcSettings.GetFromFile() to read the configuration (all utilities/examples/tests does this).

Important Notes:

• Store your IHC_ENCRYPT_PASSPHRASE securely in the system environement.
• Never commit the passphrase to version control
• Use different passphrases for different environments (dev/test/production)
• To decrypt back to plaintext: dotnet run ... -- decrypt ihcsettings.json

For complete documentation, see the IHC Settings Encrypt README.

OpenTelemtry as a logging replacement

As a more powerfull alternative to log files, the SDK (optionally) supports OpenTelemetry to view traces. To enable this change telemetry settings in the config file. The SDK should work with any OpenTel solutions. Below is listed one example.

Note, while the SDK use OpenTelemtry instead of logging. Some utilities/applications using the SDK may still use logging. Therefor the example/template specification for ihcssettings.json files retains a logging configuration.

OpenTelemetry using OpenObserve details

OpenObserve.ai provides a free, self-hosted easy to install OpenTelemetry solution. A single executable be downloaded from OpenObserve.ai. Select "Open source" version, your OS and download. Once installed and run you should be able to access OpenObserve from http://localhost:5080. From the menu select Datasource menu, Select Traces and note the Authorization key. Then update ihsettings.json with the following information but with the placeholder <Authorization Key here> replaced with your key.

OpenObserver setup:

 "telemetry": {
      "Host": "http://localhost:5080",
      "Traces": "http://localhost:5080/api/default/v1/traces",
      "Logs": "http://localhost:5080/api/default/v1/logs",
      "Headers": "Authorization=Basic <Authorization Key here>, stream-name=Ihc, organization=default"
    },

FAQ

Q: Do I need to configure my IHC before running the examples or using the API from my own code?
A: Open the standard IHC administrator app from LK, login, click access control and enable localnet or internet access + "Open for thirdparty products". Only enable internet access if you have a firewall and know how to use it securely.

Q: Why does I get a error message 'The configuration file 'ihcsettings.json' was not found and is not optional' when running examples/tests/applications. A: You must create a "ihcsettings.json" file in root folder. Copy the 'ihcsettings_example.json' file to 'ihcsettings.json' and fill out your information.

Q: Is there a NuGet package available ?
A: Not yet but might happen later if there is demand. For now just clone to repo and use the sdk project directly.

Q: Can I contribute to this project? A: Yes please. See https://docs.github.com/en/get-started/quickstart/contributing-to-projects and https://github.com/mmc41/IHCClientSDK

Q: How do I get support?
A: There is no official support for this SDK but you can post issues on the github site. https://github.com/mmc41/IHCClientSDK.