Neuro.Content.OpenApi 1.0.0

Neuro.Content.OpenApi

This repository provides the Neuro.Content.OpenApi service for the TAG Neuron(R).

Steps to create a custom service

1. Clone the repository to your development machine.

   • It has been assumed the repository will be cloned to C:\My Projects\Neuro.Content.OpenApi, see build events below.

2. Install a Neuron on your development machine, that you can use for debugging and testing.

   • Make sure the IoT Broker Windows Service is not started (Disabled or Manual), and does not start automatically. You will start it from Visual Studio when debugging. Stop the service if it started automatically after installation.
   • Update the post build events so they refer to the tools available in the Neuron installation folder.
   • Alternatively, clone the IoT Gateway repository and compile it. In the post build events, it is assumed it is cloned to C:\My Projects\IoT Gateway. It also contains the tools referenced from the build script to generate packages.

3. Make the service project the default Startup Project, and edit its Debug Launch Profile from project properties, so the folders match the folders your Neuron was installed at.

4. Compile and run the service. Make sure the console version of the Neuron is started. Once started, go to the administration page and make sure your service is available in the Software section.

5. Implement your service interfaces, as shown in code.

   • Reuse libraries used by the Neuron(R) as much as possible, to simplify distribution and facilitate fixes and updates.
   • Go through all comments in code marked with TODO.

6. Update the Manifest file so it contains all referenced assemblies and content files and folders necessary to install the service on a Neuron(R). You do not need to reference assemblies or content files that are part of the Neuron(R) distribution itself.

7. Create an installable package that can be distributed and installed on TAG Neurons.

8. Compile and test on a local development Neuron(R).

9. Once it works, sign and distribute the package on test Neurons, and later production Neurons.

10. Update project documentation for future developers, following documentation style of similar projects, for recognizability and ease of use.

11. Append project documentation with useful hints or information, if needed.

12. Provide a correct license for the repository.

Projects

The solution contains the following C# projects:

Nugets

The following external nugets are used. They facilitate common programming tasks, and enable the service to be hosted on the TAG Neuron without conflicts. For a list of general nugets available that can be used, see the IoT Gateway repository.

Installable Package

To create a package that can be distributed or installed, you begin by creating a manifest file. The Neuro.Content.OpenApi project has a manifest file called Neuro.Content.OpenApi.manifest. It defines the assemblies and content files and folders included in the package. You then use the Waher.Utility.Install and Waher.Utility.Sign command-line tools in the IoT Gateway repository, to create a package file and cryptographically sign it for secure distribution across the Neuron network. These tools are also available in the installation folder of the Neuron(R) distribution.

Generating Keys

To sign and distribute a package you will need a public and private key pair. The private key is used for signing the package, and the public key is used as part of the key required to install a package. Each time you distribute a new package, it must be signed using the same private key, or the Neuron(R) receiving the new package will discard it. Each new package received is tested if it has been signed using the same private key. Only if the signature of the new package matches the public key of the installed version, will the new package be accepted as an update to the installed package.

You will also need an AES key. The package is also encrypted using the symmetric AES cipher. This key is mainly used for obfuscating the contents of a package.

To generate a new public and private key pair, as well as the AES key, you can execute the following script from a script prompt on the Neuron(R). You can find it from the Admin page, in the Lab section. The installation key is then the concatenation of PubKey and AesKey.

Key:=Ed448();
printline("PubKey: "+Base64Encode(Key.PublicKey));
printline("PrivKey: "+select /default:EllipticCurve/@d from Xml(Key.Export()));
printline("AesKey: "+Hashes.BinaryToString(Waher.IoTGateway.Gateway.NextBytes(16)));

Security Note: The Public Key and AES Keys can be distributed together with the package to third parties for installation. They do not represent a protection by themselves, as they are considered known. The Private Key however, must not be distributed or stored in unsecure locations, including cloud storage, online repositories, etc. If anyone gets access to the private key, they will be able to create a counterfeit package of the same name.

Generating package

Once you are ready to create the installable package, you use the Waher.Utility.Install tool to create a distributable package, and the Waher.Utility.Sign tool to sign it and create a signature file. The following Command-Line prompt (Windows) provides an example of how this can be done. Here, it is assumed you are located in the C:\My Projects folder on a Windows machine, and use the tools from the compiled IoT Gateway repository. You can likewise use the same tools from an installed version of the TAG Neuron(R) to do this.

IoTGateway\Utilities\Waher.Utility.Install\bin\Release\PublishOutput\win-x86\Waher.Utility.Install.exe
    -p Neuro.Content.OpenApi.package -k [AESKEY]
    -m Neuro.Content.OpenApi.manifest

IoTGateway\Utilities\Waher.Utility.Sign\bin\Release\PublishOutput\win-x86\Waher.Utility.Sign.exe 
    -c ed448 
    -priv [PRIVKEY]
    -o Neuro.Content.OpenApi.signature
    -s Neuro.Content.OpenApi.package

Note: The command line example above are only two commands, shown on multiple rows, for readability.

Note 2: You need to replace [AESKEY] with the value of the AesKey generated using the script in the previous section. Likewise, you need to replace [PRIVKEY] with the value of PrivKey.

Once the .package and .signature files are generated, you can upload them to a test Neuron(R). The package will be automatically distributed to any connected child neurons, recursively. If the signature in the .signature file validates using any public key used on a Neuron(R) where a previous package with the same name has been installed, it will be accepted, otherwise rejected. Depending on update settings on the Neuron(R), the package will be installed automatically, installed with a delay, or deferred to the operator for manual update or install (the default).

Building, Compiling & Debugging

The repository assumes you have the IoT Gateway repository cloned in a folder called C:\My Projects\IoT Gateway, and that this repository is placed in C:\My Projects\Neuro.Content.OpenApi. You can place the repositories in different folders, but you need to update the build events accordingly. You can also use an installed Neuron(R) on your development machine, and use it instead of the IoT Gateway. If you do so, you need to update the build events and debug profiles to match the installation folder. To run the application, you select the Neuro.Content.OpenApi project as your startup project. It will execute the console version of the IoT Gateway, and make sure the compiled files of the Neuro.Content.OpenApi solution is run with it.

Gateway.config

To simplify development, once the project is cloned, add a FileFolder reference to your repository folder in your gateway.config file. This allows you to test and run your changes to Markdown, back-end script and Javascript immediately, without having to synchronize the folder contents with an external host, or recompile or go through the trouble of generating a distributable software package just for testing purposes. Changes you make in .NET can be applied in runtime if Hot Reload permits, otherwise you need to recompile and re-run the application again.

Example of how to point a web folder to your project folder:

<FileFolders>
  <FileFolder webFolder="/Neuro.Content.OpenApi" folderPath="C:\My Projects\Neuro.Content.OpenApi\Neuro.Content.OpenApi\Root\Neuro.Content.OpenApi"/>
</FileFolders>

Note: Once the file folder reference is added, you need to restart the Neuron(R) for the change to take effect.

Note 2: Once the Neuron(R) is restarted, the source for the files is taken from the new location. Any changes you make in the corresponding ProgramData subfolder will have no effect on what you see via the browser.

Note 3: This file folder is only necessary on your developer machine to give you real-time updates as you edit the files in your development folder. It is not necessary in a production environment, as the files are copied into the correct folders when the