Deploy a new simulated device

Article
08/15/2018

The Remote Monitoring and Device Simulation solution accelerators both let you define your own simulated devices. This article shows you how to deploy a customized chiller device type and a new lightbulb device type to the Remote Monitoring solution accelerator.

The steps in this article assume you've completed the Create and test a new simulated device how-to guide and have the files that define the customized chiller and new lightbulb device types.

The steps in this how-to guide show you how to:

Use SSH to access the file system of the virtual machine that hosts the Remote Monitoring solution accelerator.
Configure Docker to load the device models from a location outside the Docker container.
Run the Remote Monitoring solution accelerator using custom device model files.

Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article without having to install anything on your local environment.

To start Azure Cloud Shell:

Option	Example/Link
Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell.
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser.
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal.

To run the code in this article in Azure Cloud Shell:

Start Cloud Shell.
Select the Copy button on a code block to copy the code.
Paste the code into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux or by selecting Cmd+Shift+V on macOS.
Select Enter to run the code.

To complete the steps in this how-to guide, you need an active Azure subscription.

If you don’t have an Azure subscription, create a free account before you begin.

Prerequisites

To follow this how-to guide, you need:

A deployed instance of the Remote Monitoring solution accelerator.
A local bash shell to run the ssh and scp commands. On Windows, an easy way to install bash is to install git.
Your custom device model files, such as the ones described in Create and test a new simulated device.

Access the virtual machine

The following steps use the Azure CLI in Azure Cloud Shell. If you prefer, you can Install the Azure CLI on your development machine and run the commands locally.

The following steps show you how to configure the Azure virtual machine to allow SSH access. The steps shown assume the name you chose for the solution accelerator is contoso-simulation -- replace this value with the name of your deployment:

List the contents of the resource group that contains the solution accelerator resources:
```
az resource list -g contoso-simulation -o table
```
Make a note of the name of the virtual machine, the public IP address, and network security group - you need these values later.
Update the network security group to allow SSH access. The following command assumes the name of the network security group is contoso-simulation-nsg -- replace this value with the name of your network security group:
```
az network nsg rule update --name SSH --nsg-name contoso-simulation-nsg -g contoso-simulation --access Allow -o table
```
Only enable SSH access during test and development. If you enable SSH, you should disable it again as soon as possible.
Update the password for the azureuser account on the virtual machine to a password you know. Choose your own password when you run the following command:
```
az vm user update --name vm-vikxv --username azureuser --password YOURSECRETPASSWORD  -g contoso-simulation
```
Find the public IP address of your virtual machine. The following command assumes the name of the virtual machine is vm-vikxv -- replace this value with the name of the virtual machine you made a note of previously:
```
az vm list-ip-addresses --name vm-vikxv -g contoso-simulation -o table
```
Make a note of the public IP address of your virtual machine.

Configure Docker

In this section, you configure Docker to load the device model files from the /tmp/devicemodels folder in the virtual machine rather than from inside the Docker container. Run the commands in this section in a bash shell on your local machine:

Use SSH to connect to the virtual machine in Azure from your local machine. The following command assumes the public IP address of virtual machine vm-vikxv is 104.41.128.108 -- replace this value with the public IP address of your virtual machine from the previous section:
```
 ssh azureuser@104.41.128.108
```
Follow the prompts to sign in to the virtual machine with the password you set in the previous section.

Configure the device simulation service to load the device models from outside the container. First open the Docker configuration file:

sudo nano /app/docker-compose.yml

Locate the settings for the devicesimulation container and edit the volumes setting as shown in the following snippet:

devicesimulation:
  image: azureiotpcs/device-simulation-dotnet:1.0.0
  networks:
    - default_net
  depends_on:
    - storageadapter
  environment:
    - PCS_KEYVAULT_NAME
    - PCS_AAD_APPID
    - PCS_AAD_APPSECRET
  # How one could mount custom device models
  volumes:
    - /tmp/devicemodels:/app/webservice/data/devicemodels:ro

Save the changes.

Copy the existing device model files from the container to the new location. First, find the container ID for the device simulation container:
```
sudo docker ps
```
Then copy the device model files to the tmp folder in the virtual machine. The following command assumes the container ID is c378d6878407 -- replace this value with your device simulation container ID:
```
sudo docker cp c378d6878407:/app/webservice/data/devicemodels /tmp
sudo chown -R azureuser /tmp/devicemodels/
```
Keep the bash window with your SSH session open.
Copy your custom device model files into the virtual machine. Run this command in another bash shell on the machine where you created your custom device models. First, navigate to the local folder that contains your device model JSON files. The following commands assume the public IP address of the virtual machine is 104.41.128.108 -- replace this value with the public IP address of your virtual machine. Enter your virtual machine password when prompted:
```
scp *json azureuser@104.41.128.108:/tmp/devicemodels
cd scripts
scp *js azureuser@104.41.128.108:/tmp/devicemodels/scripts
```
Restart the device simulation Docker container to use the new device models. Run the following commands in the bash shell with the open SSH session to the virtual machine:
```
sudo /app/start.sh
```
If you want to see status of the running Docker containers and their container IDs, use the following command:
```
sudo docker ps
```
If you want to see the log from the device simulation container, run the following command. Replace the container ID with the ID of your device simulation container:
```
sudo docker logs -f 5d3f3e78822e
```

Run simulation

You can now use your custom device models in the Remote Monitoring solution:

Launch your Remote Monitoring dashboard.
Use the Devices page to add simulated devices. When you add a new simulated device, your new device models are available to choose.
You can use the dashboard to view device telemetry and call device methods.

Clean up resources

If you plan to explore further, leave the Remote Monitoring solution accelerator deployed.

If you no longer need the solution accelerator, delete it.

Next steps

This guide showed you how to deploy custom device models to the Remote Monitoring solution accelerator. The suggested next step is to learn how to connect a real device to your Remote Monitoring solution.