Working With Services¶
There are a number of API entries points related to working with services within FogLAMP.
Service Status¶
In order to discover the services registered within a FogLAMP instance and what state they are currently in the API call /foglamp/service can be used. This is a GET call and will return the set of services along with various information regarding the service. A registered service is one that is either currently running or is configured but disabled.
$ curl http://localhost:8081/foglamp/service | jq
{
"services": [
{
"name": "FogLAMP Storage",
"type": "Storage",
"address": "localhost",
"management_port": 39773,
"service_port": 46391,
"protocol": "http",
"status": "running"
},
{
"name": "FogLAMP Core",
"type": "Core",
"address": "0.0.0.0",
"management_port": 41547,
"service_port": 8081,
"protocol": "http",
"status": "running"
},
{
"name": "Notification",
"type": "Notification",
"address": "localhost",
"management_port": 40605,
"service_port": 40779,
"protocol": "http",
"status": "shutdown"
},
{
"name": "dispatcher",
"type": "Dispatcher",
"address": "localhost",
"management_port": 46353,
"service_port": 35605,
"protocol": "http",
"status": "shutdown"
},
{
"name": "lathe1004",
"type": "Southbound",
"address": "localhost",
"management_port": 45113,
"service_port": 34403,
"protocol": "http",
"status": "running"
},
{
"name": "OPCUA",
"type": "Northbound",
"address": "localhost",
"management_port": 42783,
"service_port": null,
"protocol": "http",
"status": "shutdown"
},
{
"name": "sine2",
"type": "Southbound",
"address": "localhost",
"management_port": 38679,
"service_port": 33433,
"protocol": "http",
"status": "running"
}
]
}
The data returned for each service includes
Key |
Description |
|---|---|
name |
The name of the service. |
type |
The service type. This may be one of Northbound, Southbound, Core, Storage, Notification or Dispatcher. In addition other storage types may also be installed to extend the functionality of FogLAMP. |
address |
The Address the service can be contacted via. Normally localhost or 0.0.0.0 if the service is running on the same machine as the Core service of the FogLAMP instance. |
management_port |
The management port the service is using to communicate with the core. |
service_port |
The port the service is using to expose the service API of the service. |
protocol |
The protocol the service is using for its control API. |
status |
The status of the service. This may be running, shutdown, unresponsive or failed. |
Parameters¶
You may limit the services returned by this call to a particular type by using the type= parameter to the URL.
$ curl -sX GET http://localhost:8081/foglamp/service?type=Southbound | jq
{
"services": [
{
"name": "lathe1004",
"type": "Southbound",
"address": "localhost",
"management_port": 45113,
"service_port": 34403,
"protocol": "http",
"status": "running"
},
{
"name": "sine2",
"type": "Southbound",
"address": "localhost",
"management_port": 38679,
"service_port": 33433,
"protocol": "http",
"status": "running"
}
]
}
South and North Services¶
Specific API calls exist for the two must commonly used service types, the south and north services. These give additional information and are primarily used to give the status of all south or north services in the system.
Note
In the case of the north API entry point the information returned is for both services and tasks
South Services¶
The /foglamp/south call will list all of the south service with the information above and will also list
the assets that are ingested by the service,
a count for each asset of how many readings have been ingested, this is only applicable if the plugin ingests multiple assets
the name and version of the south plugin used
and the current enabled state of the south service.
$ curl -s http://localhost:8081/foglamp/south |jq
{
"services": [
{
"name": "lathe1004",
"address": "localhost",
"management_port": 45113,
"service_port": 34403,
"protocol": "http",
"status": "running",
"assets": [
{
"count": 520774,
"asset": "lathe1004"
},
{
"count": 520774,
"asset": "lathe1004Current"
},
{
"count": 520239,
"asset": "lathe1004IR"
},
{
"count": 260379,
"asset": "lathe1004Vibration"
}
],
"plugin": {
"name": "lathesim",
"version": "1.9.2"
},
"schedule_enabled": true
},
{
"name": "sine2",
"address": "localhost",
"management_port": 38679,
"service_port": 33433,
"protocol": "http",
"status": "running",
"assets": [
{
"count": 734,
"asset": "sine2"
},
{
"count": 373008,
"asset": "sine250"
}
],
"plugin": {
"name": "sinusoid",
"version": "1.9.2"
},
"schedule_enabled": true
},
{
"name": "test1",
"address": "",
"management_port": "",
"service_port": "",
"protocol": "",
"status": "",
"assets": [
{
"count": 76892,
"asset": "sinusoid"
},
{
"count": 125681,
"asset": "sinusoid2"
}
],
"plugin": {
"name": "sinusoid",
"version": "1.9.2"
},
"schedule_enabled": false
},
{
"name": "testacl",
"address": "",
"management_port": "",
"service_port": "",
"protocol": "",
"status": "",
"assets": [
{
"count": 76892,
"asset": "sinusoid"
}
],
"plugin": {
"name": "testing",
"version": "1.9.2"
},
"schedule_enabled": false
},
{
"name": "dsds",
"address": "",
"management_port": "",
"service_port": "",
"protocol": "",
"status": "",
"assets": [],
"plugin": {
"name": "Expression",
"version": "1.9.2"
},
"schedule_enabled": false
}
]
}
$
Service Types¶
FogLAMP supports a number of different service types, some of which are included with the base FogLAMP installation and others that must be installed separately if required.
Note
The API entry points in this section require that the FogLAMP installation has been configured with access to a FogLAMP package repository.
Installed Service Types¶
In order to find out what service types are installed in the system the /foglamp/service/installed call can be used.
$ curl http://localhost:8081/foglamp/service/installed
{"services": ["storage", "north", "dispatcher", "notification", "south"]}
Note
All FogLAMP instances have the storage, south and north services installed by default when the FogLAMP core is installed.
Available Service Types¶
To find out what services are available to be installed from the package repository configured for your FogLAMP instance use the API /foglamp/service/available.
$ curl -q http://localhost:8081/foglamp/service/available |jq
{
"services": [
"foglamp-service-notification"
],
"link": "logs/220831-13-26-25-list.log"
}
The link in the returned JSON is a link to a log file that shows the interaction with the package repository.
Install a Service Type¶
To install a new service type the POST method can be used on the /foglamp/service API call with the parameter action=install.
$ curl -X POST http://localhost:8081/foglamp/service?action=install -d'{"format":"repository", "name": "foglamp-service-notification"}'
This will install the named service from the package repository.
Note
In order to install a package the package repository must be configured and accessible.
Creating A Service¶
A new service can be created using the POST method on the /foglamp/service API call. The payload passed to this request will determine at least the service type and the name of the new service, however it may also contain further configuration which is dependent on the type of the service.
The minimum payload content that must be in every create call for a service is the name of the new service, the type of the service and the enabled state of the service. This can be used for example to create a notification service or a control dispatcher service that need no further configuration.
$ curl -X POST http://localhost:8081/foglamp/service -d'{ "name" : "Notifier", "type" : "notification", "enabled" : "true" }'
Or for a control dispatcher
$ curl -X POST http://localhost:8081/foglamp/service -d'{ "name" : "Control", "type" : "dispatcher", "enabled" : "true" }'
A north or south service need some extra configuration in the payload. These service type must always have a plugin and can optionally be passed configuration for that plugin. If no plugin configuration is given then the plugins default configuration values will be used.
To create a south service using the default values of the sinusoid plugin.
$ curl -X POST http://localhost:8081/foglamp/service -d'{ "name" : "Sine", "type" : "south", "enabled" : "true", "plugin" : "sinusoid" }'
In the next example we create a north plugin that will send data to another FogLAMP instance using the HTTPC plugin. We set the value of the configuration item URL in the plugin to be the URL of the concentrator FogLAMP instance.
$ curl -sX POST http://localhost:8081/foglamp/service -d '{"name": "HTTP", "plugin": "httpc", "type": "north", "enabled": true, "config": {"URL": {"value": "http://concentrator.local:6683/buildingA"}}}'
Stopping and Starting Services¶
Services within FogLAMP are started and stop via the scheduler, normally a service will be started via a schedule that defines the service to run at startup of FogLAMP. This ensures that the service runs when FogLAMP is started and will continue to run until FogLAMP is stopped. To implicitly stop a service the schedule must be disabled.
Disabling a schedule associated for a service will also stop the service. The service will not then be restarted, even if FogLAMP is restarted, until the schedule is again enabled.
To disable a schedule you can call the /foglamp/schedule/{schedule_id}/disable API call, however this requires you to know the ID of the schedule associated with the service. It is possible to find this for a given service, as the schedule name is the same as the service name, however it is simpler to use the API call /foglamp/schedule/disable as this can be passed the name of the schedule rather than the schedule ID. Since the schedule name and the service name are the same, we effectively pass the name of the service we wish to disable.
To disable the service call Sine we would use the following curl command.
$ curl -X PUT http://localhost:8081/foglamp/schedule/disable -d '{"schedule_name": "Sine"}'
To enable the service again we can use the /foglamp/schedule/enable API call, this takes an identical payload to the disable API call.
$ curl -X PUT http://localhost:8081/foglamp/schedule/enable -d '{"schedule_name": "Sine"}'
Deleting a Service¶
Services may be deleted from the system using the /foglamp/service API call with the DELETE method. When a service is deleted it will be stopped and the service, configuration for the service and the associated schedule will be removed. Any data that has been read by the service will however remain in the readings database.
To delete the service named Sine
$ curl -X DELETE http://localhost:8081/foglamp/service/Sine