Introduction

HumanOS® SAL.ServiceController is a control and monitoring application to manage an installed HumanOS Service. The ServiceController is part of the HumanOS® Runtime.

Installation

The installer provided by CyberTech Engineering is named in the following way: HumanOS.SAL.ServiceController-$(os)-$(platform)-v$(version)-$(build-nr)

• $(os) Currently, only windows is available (win)
• $(platform) Currently, only x64 platform is supported
• $(version) HumanOS SAL service controller version
• $(build-nr) Build number

Example: HumanOS.SAL.ServiceController-win-x64-v1.3.7-015.exe

Installation Path

Default installation: C:\Program Files (x86)\CyberTech\HumanOS.SAL.ServiceController\

Configuration

The HumanOS® SAL.ServiceController requires a configuration. The configuration file is named “appsettings.json” and is located in $(install directory).

Following fields are required for this application config:

Name	Description	DataType
CustomInfo	Custom information text about the product or the system	System.String
ProductName	Custom name of the product	System.String
ProductPath	Path* to the HumanOS product binary (.exe) where the installed service points to. Is used to display the versions, in Process mode, this executable will be started. CAUTION: This path must point to a valid HumanOS product containing the HumanOS.Runtime	System.String
MonitoringInterval	Time interval in milliseconds where the application calls the state of the service. Default value is 250	System.Int32
DisableSettings	[opt] Disables the settings for the user. Default is false. True = Settings are disabled	System.Boolean
ServiceConfig	Configuration for the Service	TServiceConfiguration
CustomImages	[opt] It is possible to customize the service controller with a custom logo and custom icons	TCustomImageConfig

The type TServiceConfiguration contains following fields:

Name	Description	DataType
Type	Type of the monitored service. Possible vlaues are: (Process, Service)	EServiceType
AutoRestartOnFailure	[opt] Auto restart option on service or process failure, default is false. True = restarts the service or process after a crash of the service or process.	System.Boolean
Autostart	[opt, only for service type Process] Autostart option, default is false. True = starts the service after startup of the tray application.	System.Boolean
Name	[only for service type Service] Name of the service. IMPORTANT: This property must exactly match the name of the installed service. The SAL.ServiceController application searches the service by this name	System.String

The type TCustomImageConfig contains following fields:

Name	Description	DataType
LogoImage	[opt] Path to custom logo. Place here a path to the logo image*	System.String
StoppedIcon	[opt] Taskbar icon that symbolizes the stopped state. Must be an .ico file*	System.String
StartupIcon	[opt] Taskbar icon that symbolizes the startup state. Must be an .ico file*	System.String
RunningIcon	[opt] Taskbar icon that symbolizes the running state. Must be an .ico file*	System.String

* Can be an absolute path or a relative path related on folder where the application is installed.

An Example of the configuration for a service is shown below:

{
  "CustomInfo": "Place here your custom Text",
  "ProductName": "HumanOS.IoT.Gateway",
  "ProductPath": "..\\..\\..\\..\\..\\binaries.net\\HumanOS.IoT.Gateway.exe",
  "ServiceConfig": {
    "Type": "Service",
    "Name": "HumanOS.IoT.Gateway",
  },
  "MonitoringInterval": 250,
  "CustomImages": {
    "LogoImage": "Images\\logo.png",
    "StoppedIcon": "Images\\stopped.ico",
    "StartupIcon": "Images\\startup.ico",
    "RunningIcon": "Images\\running.ico"
  }
}

An Example for the configuration for a process is shown below:

{
  "CustomInfo": "Place here your custom Text",
  "ProductName": "HumanOS.IoT.Gateway",
  "ProductPath": "..\\..\\..\\..\\..\\binaries.net\\HumanOS.IoT.Gateway.exe",
  "DisableSettings": true  
  "ServiceConfig": {
    "Type": "Process",
    "Autostart": true
    "AutoRestartOnFailure": true
  },
  "MonitoringInterval": 250,
  "CustomImages": {
    "LogoImage": "Images\\logo.png",
    "StoppedIcon": "Images\\stopped.ico",
    "StartupIcon": "Images\\startup.ico",
    "RunningIcon": "Images\\running.ico"
  }
}

Following image shows the meaning of the settings:

Service controller Operation Manual

User Interface

Once, the application is started, a new tray icon will appear in the taskbar. By clicking on the icon, the following menu will open:

Over this menu the service can be started or stopped. The service controller can be terminated by clicking quit. More information can be found under About $(ProductName). The ShieldIcons are only displayed when the property Type of ServiceConfiguration equals “Service”.

caution

Change of the service state requires administrator privileges when the property Type of ServiceConfiguration equals “Service”. By clicking the start or stop command, Windows asks for privileges through the UAC Dialog.

In the About window, information about the product, the service, the service monitor, and the HumanOS versions can be found.

States

Monitor State

The monitor state indicates, if the service can be found and get information about it is possible. This state is visible under "Monitor Info: / State".

Name	Description
Connected	The specified service is found and installed in the operating system
Disconnected	Could not find the specified service or no access to read data about it. Maybe the service is not installed.

Service State

The service state indicates the state of the service. This state is visible under "Service Info: / State". The tray icon will also switch it’s color by changing the state.

Name	Description	Default taskbar Icon	Custom Imges
Unknown	Could not find the specified service or no access to read data about it. Maybe the service is not installed.		StoppedIcon
Stopped	The service is stopped		StoppedIcon
StartPending	The start of the service is pending		StartupIcon
StopPending	The stop of the service is pending		StartupIcon
ContinuePending	Continue execution of the service is pending		StartupIcon
PausePending	The pause state is pending		StartupIcon
Paused	The service is paused		StartupIcon
Running	The service is running		RunningIcon

Process State

The process state indicates the state of the process. This state is visible under "Process Info: / State". The tray icon will also switch it’s color by changing the state.

Name	Description	Default taskbar Icon	Custom Imges
Stopped	The service is stopped		StoppedIcon
Startup	The service is starting up		StartupIcon
Shutdown	The service is shutting down		StartupIcon
Running	The service is running		RunningIcon

Settings

By clicking the Settings button, all parameters belonging the HumanOS product can be edited. Following settings can be edited via the settings dialog:

• Service Name
• Monitoring Interval
• Product Path (Product executable)

caution

Depending on the installation folder, changing of the settings requires administrator privileges. By clicking the save command, Windows asks for privileges through the UAC Dialog.

By clicking the Save button, the file appsettings.json in the installation folder will be overwritten. With the Button “SelectFile” the product can be selected with an open-file-dialog.

Platform extension

The service controller can be configured to function as an HumanOS® IoT Platform extension. To do so, add the following text lines to the configuration file (adjust the data to your platform):

...
,
  "AgentSettings": {
    "Username": "",
    "Password": "",
    "Address": "127.0.0.1",
    "Port": 1883
  }

The about dialog will now show an additional button:

The platform configuration settings can be viewed as readonly:

The service controller is now configured to function as part of the platform.