Getting Started - CDE-GMA/UIC.net-mono.c-sharp GitHub Wiki

Table of content

Setup UIC

The UIC.NET reference implementation was written in C#. The IDE is Visual Studio 2017. The following steps guides you through the setup process:

  1. Download and install the Visual Studio 2017 (a free Community Edition is available)
  2. create a fork of the repo in order to make changes without interfering this repository
  3. clone or download the repo to your local drive and open the solution with the Visual Studio IDE
  4. Make sure that UIC.SGeT.Launcher-Project is set as Startup Project
    • The project name in the solution explorer must be bold
    • If not, right-click on the project in the solution explorer and click on set as start project
  5. Configure the needed target platform (x64 is recommended)
  6. Compile UIC.NET solution

octocat

Communication Agents

The UIC is able to use different communication agents, which are used to communicate with the supported Iot Services AWS, M2MGO, AZURE. To select one of the communication agents, a config file has to be created called uic_config.json and placed in the same directory as the UIC.SGeT.Launcher.exe, which might be UIC.net-mono.c-sharp\UIC\UIC.SGeT.Launcher\bin\x64\Release depending which build target you choose in VS2017. When there is no uic_config.json in the directory a backup file uic_config_bak.json will be created, which can be modfified and canged to uic_config.json

uic_config.json:

{
  "ProjectKey": "26895846c960465ebd89f28d10e6460c",
  "IsEdmSnychronizationEnabled": true,
  "ProjectJsonFilePath": ".\\project.json",
  "IsRemoteProjectLoadingEnabled": true,
  "CommunicationAgent": "[CommunicationAgent]"
}

M2MGO

  1. In Order to use the M2MGO communication agent, replace the "[CommunicationAgent]" in the uic_config.json with "M2MGO".
  2. Change the Project Key to the one that suits your project.
  3. Start the UIC by double cklicking the UIC.SGeT.Launcher.exe.

Microsoft AZURE

  1. Create an Azure Account. You have to provide Payment information.

  2. Create an Azure Iot Hub

  3. Create 2 Iot Devices "uic_device_mockup" and "uic_device_eapi"

    • After that you get a connection String of both devices that looks like this:
    HostName={YourIoTHubName}.azure-devices.net;DeviceId=uic_device_mockup;SharedAccessKey={YourSharedAccessKey}
HostName={YourIoTHubName}.azure-devices.net;DeviceId=uic_device_eapi;SharedAccessKey={YourSharedAccessKey}

  4. Create a config file "azure_communication_agent.json" and insert {YourIoTHubName} and the {SharedAccessKey} of the 2 devices. Place this config file in the same directory as UIC.SGeT.Launcher.exe. If this config file is not privided when starting the UIC, a bakckup config "azure_communication_agent_bak.json" will be created, that can be modfied and renamed.

    	{
		"IotHubUri": "{YourIoTHubName}.azure-devices.net",
		"DeviceKeys": {
			"uic_device_mockup": "{YourSharedAccessKey}",
			"uic_device_eapi": "{YourSharedAccessKey}"
		},
		"EdmMappings": {
			"1e7b861c-d6a0-4993-812e-0ffd42a4c77d": "uic_device_mockup",
			"b3bb9ffa-43ba-49f9-bbb2-40d1de291215": "uic_device_eapi",
			"d958bb24-7a1a-4cb6-bb7f-3a5868d3170d": "uic_device_eapi"
		}
	}

  5. Modify uic_config.json and change the "[CommunicationAgent]" with "AZURE"

    {
	"ProjectKey": "26895846c960465ebd89f28d10e6460c",
	"IsEdmSnychronizationEnabled": true,
	"ProjectJsonFilePath": ".\\project.json",
	"IsRemoteProjectLoadingEnabled": true,
	"CommunicationAgent": "AZURE"
}

  6. Start the UIC by doubleclicking the UIC.SGeT.Launcher.exe

  7. Go to the Azure Iot Portal and navigate to you Iot Hub. On the bottom you can see the count of the Messages that are sent from the UIC on your device to the azure iot hub. octocat

  8. If you want to check the content of the Messages that are sent from the UIC to the azure, go to the Azure Portal and navigate to the azure cloud shell on the top of the Page. octocat

In the azure cloud shell enter following command to add the Microsoft Azure Iot Extension for Azure CLI to you cloud hell instance

az extension add --name azure-cli-iot-ext

After that you can enter following command to read the messages that are sent to the iot hub.

az iot hub monitor-events --hub-name {YourIoTHubName} --output table

octocat

AmazonWebServices (AWS)

The UIC needs an addon in order to communicate with the AmazonWebServices. There is no AWS SDK available in C# yet, so an Addon is required. The Addon UIC-AWS-ConnectionServer (UAS) is written in Java and has to be built and run parallel to the UIC. The UAS communicates with the UIC/HAW.AWS.CommunicationAgent over the REST API. Detailed Information about the HAW.AWS.CommunicationAgentand the UAS are available in the HAW Communication Agent Documentation

  1. Compile the UAS. Follow the instructions in the UAS Installation and Setup

  2. Create an AWS account. Payment Information must be provided

  3. In the AWS Console search for "Iot Core". There you can register a device. Download the certification files after the registration of your devices afterwards. They should look like this:

    • 2a540e2346-certificate.pem.crt
    • 2a540e2346-private.pem.key
    • 2a540e2346-public.pem.key

  4. After you have successfully built the UAS you should have following java executable in the directory \UIC.net-mono.c-sharp\UIC‐AWS‐ConnectionServer\target\AWS-UIC-ConnectionServer-1.0.jar

    • Copy the certification files from above into this directory nex to the AWS-UIC-ConnectionServer-1.0.jar
    • create a config file called "config.properties" and place also in this directory
    # The region of the aws server that is used (f.e. server: data.iot.us-west-2.amazonaws.com => region: us-west-2)
region=us-west-2


# the certificate file
cert=INSERT_CERTIFICATE_FILENAME


# the ClientID for this Instance. MUST be unique in the whole project
clientid=CHANGEME123


# port for the REST API of the uic
port_uic = 8081


# port for the REST API of the UIC-AWS-ConnectionServer
port_uas = 8080


# The praefix of the aws server that is used (f.e. server: data.iot.us-west-2.amazonaws.com => prasefix: data   )
praefix=data


# the file that contains the private key of the certificate
private_key_file=INSERT_PRIVATE_KEY_FILENAME


# the quality of service that is sued for publishes
qos=1


# the topic that is used for pushing data such as Attributes and DataPoints
push_topic=myProject/push


# the topic that is used for the Initiation
# CAN be overwritten in the http-post-request
init_topic=myProject/init 


# the topic that is used for the subscription and the backchannel feature
backchannel_topic=myProject/back
    • Change following parameter of config.properties:
      • region=us-west-2: Use the region which you have used by creating your AWS Account. You can check it in the top right corner of the AWS console.
        • octocat
      • cert=INSERT_CERTIFICATE_FILENAME: Enter the File name of the certification file with the ending .cert, e.g. 2a540e2346-certificate.pem.crt
      • private_key_file=INSERT_PRIVATE_KEY_FILENAME: Enter the private key file, e.g. 2a540e2346-private.pem.key

  5. Edit the uic_config.json and add the "AWS" in the filed "[CommunicationAgent]"

    {
	"ProjectKey": "26895846c960465ebd89f28d10e6460c",
	"IsEdmSnychronizationEnabled": true,
	"ProjectJsonFilePath": ".\\project.json",
	"IsRemoteProjectLoadingEnabled": true,
	"CommunicationAgent": "AWS"
}

  6. Create a another file called also config.properties and place it next to the UIC.SGeT.Launcher.exe and the uic_config.json. This config file specifies the ports, which the REST API should use. The files looks like this:

    # port for the REST API of the uic
port_uic = 8081
# port for the REST API of the UIC-AWS-ConnectionServer
port_uas = 8080

  7. Start the UAS

    • In order to start the UAS you have to launch the AWS-UIC-ConnectionServer-1.0.jar located in the target folder.
    • You have to create a .bat file to launch this .jar file properly.
    cd C:\Your\Path\to\UIC.net-mono.c-sharp\UIC‐AWS‐ConnectionServer\target
java -jar AWS-UIC-ConnectionServer-1.0.jar
pause

  8. Start the UIC

    • To start the UIC with the HAW.AWS.CommunicationAgent you have to launch the UIC as an Administrator, because the REST API needs admin rights.
    • Navigate to the UIC.SGeT.Launcher.exe an verify that the config.properties and the uic_config.json are in the same directory
    • Right Click on the UIC.SGeT.Launcher.exe and run as Administrator.

  9. Verify, that the messages are sent to the AWS Iot Core.

    • Go to https://aws.amazon.com/ and Sign in to the Console on the top right corner of the page.
    • Navigate to Iot Core and click on Test
    • There you can Subscribe to the Topic that is specicfied in the config.properties of the UAS, which is by Default "myProject/push" octocat
    • When the UAS and UIC are running correctly you see Mockup MQTT Messages from the UIC octocat