Use standard and custom commands

Start a task

You can run a standard or a custom command on a gateway from IIoT Core Services by initiating a task.

Before you begin

To be able to run a command on a gateway device, it must show a status of Online on the Devices page in the IIoT Core Services UI.

Procedure

In the IIoT Core Services UI, click the Device tab, then click Devices.
Navigate to the gateway device for which you want to create a task and click Task.

NoteThe Task option appears only for gateway devices that have been enrolled.

In the Start Task window, select a command from the Select Command list.

Custom commands are prefixed with the word Custom.

If the command has environment variables, make the necessary parameter selections in the Environment Variables section.

The following table lists the available standard commands:

Standard commands	Description
reboot	Reboot the gateway device.
network information	Get network information, including firewall and port information.
device info	Get device information for the gateway device, including number of Core devices, memory, and disk size.
resource usage	View usage of computing resources, including CPU, memory, and disk space.
get firewall rules	Show the current firewall rules in the gateway.
add port to firewall rules	Enable a port to accept traffic to the gateway. This command is useful when you want to load and run your own container with an application that requires a port to be open on the gateway. CautionAn open port might expose the gateway to cyber exploits or attacks. Follow network security best practices or consult your IT security administrator before using this command.
remove port from firewall rules	Disable traffic to a specified port on the gateway. Use this command to reverse the Add port to firewall rules command when the corresponding container application is no longer needed. Removing ports that are no longer needed helps reduce the security risk.
list containers	List all running containers.
purge container volume	Purge data in the container volume on the gateway.

Click Confirm.

Results

The task is created. To see the newly created task and its status, click the Device tab, and then click Tasks.

Delete a task

You can use IIoT Core Services to delete a task from the Task list.

CautionDo not start a task unless you are confident that you want the task to be executed. After the command is transmitted to the gateway, it is executed and cannot be undone. The Delete function removes only the corresponding task from the task repository in IIoT Core Services.

Procedure

In the IIoT Core Services UI, click the Device tab, then Tasks.
Navigate to the task that you want to delete, select the Actions menu, and then click Delete.
Click Delete again to confirm deletion of the task or click Cancel to keep the task.

Results

If the task is in the Running or Queued state when you click Delete, the task is interrupted and deleted before it is sent to the gateway. If the task is in the Success state, it is deleted and removed from the Task list.

View tasks and task status in IIoT Core

You can view current tasks running on a gateway device along with the device status in the IIoT Core Services UI.

The task status overview is located in the Tasks sub-tab of the Device tab.

Procedure

Click the Device tab, and then click Tasks.
Navigate to the task that you want to review.

In the Status column, review the task status.

The following table lists the available tasks statuses and descriptions for each status.

Status	Description
Queued	A task is placed in a queue when a condition, such as a lost connection, prevents the task from being transmitted to the gateway device.
Running	The task is running and active.
Success	The task successfully completed.
Failed	The task encountered an error and did not complete. Restart the task.
Canceled	The task was cancelled while in the Queued and Running state.

Click View, and then click either the History or Result tab to see task details.

Create a custom command

You can add a custom command in IIoT Core Services by writing a Shell script or by uploading a file that runs the needed functionality.

Before you begin

To create a command using a custom container image, you must first upload the custom command tar file to the IIoT Core repository and push the file to the Docker Trusted Registry on the IIoT Gateway.

Procedure

In the IIoT Core Services UI, click the Device tab, and then click Commands.
Click Add Command.

On the Add Command page, complete the needed information.

Field	Description
Name	Enter a descriptive name for the custom command. This name appears in the Select Command list in the Start Task window.
Version (Optional)	Specify a version number to track the command version.
Description (Optional)	Provide a convenient description, such as the purpose of the command.
Timeout Seconds	Specify how long the command should try to execute before canceling the attempt.
Type (Optional)	Specify the runtime (Shell, Python, or custom). If you select a custom type, click the Container Image Type list to select from available images in the software repository. TipIf the custom container tar file that you want to use is not in the list, verify that the file was uploaded to the IIoT Core repository and pushed to the Docker Trusted Registry on the IIoT Gateway.

(Optional) Add environment values by clicking + Add.

Field	Description
Key Name	Name of a parameter to appear in the Environment Variables area of the Start Task window. ExampleSet Start Time
Default Values	Default value for the new parameter.
Description	Helpful information about the command, such as the purpose of the parameter.

In the Upload section, upload a container application, by either using drag-and-drop or browsing to select the file.
When a file is uploaded, the file name appears with other options in the table that preceeds the Drag and drop or Select files box, in the Upload section.
Under File Path, enter the file path of the container application.
In the Entry Point Shell Script window, enter the shell commands needed to launch the container that you are attaching.
Click Save.

Results

The custom command is sent to the gateway and is added to the Commands page in IIoT Core Services.

Edit a custom command

You can edit a custom command in the IIoT Core Services Commands inventory.

NoteYou cannot edit standard commands. You can only edit custom commands.

Procedure

In the IIoT Core Services UI, and then click the Device tab, then the Commands tab.
To edit a custom command, select Edit from the Actions menu for that command.
Make the necessary edits.
Click Save.

Results

The edits are saved in the repository and the custom command information is updated in the Commands list.

Delete a custom command

You can delete a custom command from the Commands inventory in IIoT Core Services.

NoteYou cannot delete standard commands.

Procedure

In the IIoT Core Services UI, select the Device tab, then the Commands tab.
Navigate to the command that you want to delete, and then click the trash icon to delete the command.
Click Delete to confirm the deletion or click Cancel to keep the command in the inventory.

Results

The custom command is deleted and removed from the list on the Commands page.

Examples of using custom commands

This section gives specific examples of how you can use the IIoT Core Services UI to create custom commands.

Create and run a custom command using a Python script
Create and run a custom command using a Shell script
Create and run a custom command using software upload

Create and run a custom command using a Python script

In this example, we will create a custom command by uploading a Python script from a drive location by using the IIoT Core Services UI.

Before you begin

The gateway must be enrolled and show a status of Online on the Devices page in the IIoT Core Services UI.
For the sake of this example, you must create a Python script called mqtt-publisher.py and make it available in an accessible drive location.

Procedure

In the IIoT Core Services UI, click the Device tab, and then click Commands.
Click the Add Command button.
Add the following information in the General section on the Add Command page.

Field Description (example)
Name Custom-MQTT-Test
Version 1.0
Description Sample test of a MQTT custom command.
Timeout Seconds 60
Container Image Type Python3.9
In the Environment Values section, click + Add:
In the Add Environment Value window, enter the information from the following table:

Key Name Default Values Description
MQTT_SERVER IP address Server IP address
PUBLISH_MESSAGE Message sent by custom command test. Text to be displayed when published
In the Upload section, upload the mqtt-publisher.py application by either using drag-and-drop or browsing to select the file.
Under File Path, enter the file path of the container application.
In the Entry Point Shell Script box, enter the following shell commands that are needed to launch the container:
```
cd <file_path>
pip install -r requirements.txt
python mqtt-publisher.py
```
Click Save.
Find the new command near the top of the list on the Commands page.
On the Devices sub-tab, find the gateway that you want to apply the new custom command to and then click Task.
In the Start Task window, select the newly created custom command, Custom - Custom-MQTT-Test, from the Select Command list, and then click Confirm.
Click the Tasks sub-tab, find the task near the top of the list, and verify that the task was successfully executed.
Click View on the task to access task details.
Click the Result sub-tab to see the output.

Field	Description (example)
Name	Custom-MQTT-Test
Version	1.0
Description	Sample test of a MQTT custom command.
Timeout Seconds	60
Container Image Type	Python3.9

Key Name	Default Values	Description
MQTT_SERVER	`IP address`	Server IP address
PUBLISH_MESSAGE	Message sent by custom command test.	Text to be displayed when published

Create and run a custom command using a Shell script

In this example, we will create a custom command using a simple Shell script.

Before you begin

The gateway must be enrolled and show a status of Online on the Devices page in the IIoT Core Services UI.

Procedure

In the IIoT Core Services UI, click the Device tab, and then click Commands.
Click Add Command.
Add the following information on the Create Command page.

Field Description (example)
Name Custom-Shell
Version 1.0
Description Custom Shell command script
Timeout Seconds 60
Container Image Type Shell
In the Environment Values section, click + Add.
In the Add Environment Value window, enter the information from the following table:

Key Name Default Values Description
NAME IIoT Core name Description of the NAME environment parameter
VERSION 5.1 Version number for this custom command parameter
In the Entry Point Shell Script box, enter the following shell commands that are needed to launch the container:
```
echo "Hello" ${NAME}
echo "Start Version:" ${VERSION}
```
Click Save.
The new command is shown at the top of list on the Commands page.
On the Devices sub-tab, find the gateway that you want to apply the new custom command to and then click Task.
In the Start Task window, enter the information from the following table and click Confirm:

Field Definition
Select Command Select the newly created custom command, Custom - Custom-Shell.
NAME My environment variable name.
VERSION 1.0.
Click the Tasks sub-tab, find the task near the top of the list, and verify that the task was successfully executed.
Click View on the task to access task details.
Click the Result sub-tab to see the output.

Field	Description (example)
Name	Custom-Shell
Version	1.0
Description	Custom Shell command script
Timeout Seconds	60
Container Image Type	Shell

Key Name	Default Values	Description
NAME	IIoT Core name	Description of the NAME environment parameter
VERSION	5.1	Version number for this custom command parameter

Field	Definition
Select Command	Select the newly created custom command, Custom - Custom-Shell.
NAME	My environment variable name.
VERSION	1.0.

Create and run a custom command using software upload

In this example, we will create a custom command by uploading a container image to the repository by using the IIoT Core Services UI.

Before you begin

The gateway must be enrolled and show a status of Online on the Devices page in the IIoT Core Services UI.
The custom command tar file must be uploaded to the IIoT Core repository and pushed to the Docker Trusted Registry on the IIoT Gateway.
For instructions on how to tag and upload a container image to the IIoT Core Services repository, see Manage container software.

Procedure

In the IIoT Core Services UI, click the Device tab, then click Commands.
Click Add Command.
Add the information from the following table on the Add Command page.

Field Description (example)
Name Custom image
Version 1.0
Description Uploaded MQTT custom command.
Timeout Seconds 60
Container Image Type Custom
By selecting Custom for the Container Image Type, the Image Name list appears.
Select an image that is in the software repository from the Image Name list.
In the Environment Values section, click + Add to add the information from the following table:

Key Name Default Values Description
MQTT_SERVER IP address Server IP address
PUBLISH_MESSAGE Message sent by custom command test. Text displayed when published
In the Entry Point Shell Script box, enter a script such as the following script to launch the container:
```
#!/bin/sh
echo "hello"
ping www.google.com -c 5
```
Click Save.
Find the new command near the top of the list on the Commands page.
On the Devices sub-tab, find the gateway that you want to apply the new custom command to and click Task.
In the Start Task window, select the newly created custom command, Custom - Custom-Image, and then click Confirm.
Click the Tasks sub-tab, find the task near the top of the list, and verify that the task was successfully executed.
Click View on the task to access task details.
Click the Result sub-tab to see the output.