How To: Deploy UDI on Linux/Raspberry Pi

Prerequisites

  • Develop a UDI Driver targeting .NET Standard or .NET Core 2.0+
  • Create a .NET Core 2.0+ Hosting Application using the UDI Driver
  • Install .NET Core on your Linux device. This can be done with the following command: 
    sudo apt-get install libunwind8 libunwind8-dev gettext
  • This tutorial can be tested with the OpenWeatherMap API Driver example found in the OAS installation directory under Universal Drivers/Standard/OpenWeatherMapDriver and consists of a console app and driver projects. Versions for both VB and C# are provided and you can use either one for this tutorial.
  • The OpenWeatherMap API Driver requires an API Key provided by OpenWeatherMap.org. Sign up for a free account to get your API Key which you will need to paste into the configuration screen for the Driver after starting it up.

Deployment

Step 1

Open a Windows console “As Administrator” navigate to the project directory for the host app and execute the following:

dotnet publish -c Release -r linux-arm

A new directory will be created containing the deployable application will be found in your project folder under:

\bin\Release\netcoreapp2.0\linux-arm\publish\

Step 2

Modify the appsettings.json file to point to your OAS server.

Locate the file in the “publish” directory and edit with any text editor or Visual Studio. Change the ServiceNode field to the IP address of your OAS Server and make sure the server firewall allows bidirectional communication on port 58727.

Additionally, you should change the MachineName field to be a unique identifier for your Linux device. This will be added to the driver name within the OAS Configuration app for easily identifying it, especially when deploying multiple instances of the same driver on several devices.

Step 3

Copy the “publish” directory to your Linux device using any transfer method you prefer, for example: FTP, SFTP, USB Drive, etc.

Step 4

Log into your Linux device via SSH and then navigate to the “publish” directory, then set permissions on the compiled app so that it can be executed. Do this by using the chmod command like so:

chmod 755 ./CoreDriverHost

Your app is now marked as an executable within Linux and can be started from the console, which we’ll do in the next step.

Step 5

Test your host app by executing it at the command line:

./CoreDriverHost

Note: this will work from within the directory containing the app. If you are in a different path, you would write the whole path to the executable.

To stop your app, just execute Ctrl-C

Step 6

Once your hosting app is running, you can open the OAS Configuration app to configure the driver and see data flowing.

Be sure to enter your OpenWeatherMap.org API Key into the Driver Configuration screen. In the OAS Configuration app, go to Configure > Drivers, and select the OpenWeatherMap API Driver. Then paste your key into the field marked “API Key” and click Apply Changes. This step will need to be repeated for any installation of your driver including a deployment to a Linux device as described below.

 

Configure to run as a Linux Service or Daemon

You can now configure your app as a daemon for Debian Linux or Raspberry Pi so it can run when the system starts, and without a logged-in user.

Step 1

Ensure that you have systemd installed on your device by executing:

sudo apt-get install -y systemd

Step 2

Create a user under which the app will execute (choose a username and password):

sudo useradd -m username -p userpass

You can use an existing user, but keeping it separate from existing login accounts is advised, as you will be able to manage application permissions separate from any users on the system.

Step 3

Create a configuration file for the app with the filename “oas-driver-host.service”.
This filename can be anything you choose, but it will also be the name of the daemon, so choose a unique name. The configuration file should contain the following text. You can modify the “Description” and “SyslogIdentifier”, making sure the SyslogIdentifier matches the filename you choose. This configuration file can be created elsewhere and uploaded to the Linux device at the location /etc/systemd/system:

[Unit]
Description=.NET Core Driver Host

[Service]
ExecStart=/home/pi/publish/CoreDriverHost
WorkingDirectory=/home/pi/publish
User=oasuser
Group=oasuser
Restart=on-failure
SyslogIdentifier=oas-driver-host
PrivateTmp=true

[Install]
WantedBy=multi-user.target

Step 4

Navigate to /etc/systemd/system and register the daemon:

sudo systemctl daemon-reload
sudo systemctl enable oas-driver-host.service

Step 5

Manually start the daemon using the systemctl command:

sudo systemctl start oas-driver-host.service

You can also start the daemon using the service command:

sudo service oas-driver-host start

Stopping the daemon is accomplished using the same commands, but replacing “start” with “stop”.

Step 6

Tail the log to see the console output in real time.
You can log in with a separate console and execute:

journalctl --unit oas-driver-host --follow

This command will continue running until you hit Ctrl-C and continually display any console messages from the daemon. This is useful for debugging.

Step 7

You can confirm communications to your OAS Server by opening up the OAS Configuration app.

Go to Configure > Drivers and locate the connected driver in the left-hand pane. You should see it listed as “OpenWeatherMap API Driver – YourMachineName” where YourMachineName is the MachineName identifier you chose in the appsettings.json file.