Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The device registration is a 2 step process. First RegisterDeviceRequest and RegisterDeviceResponse are exchanged between device and platform. Second ConfirmRegisterDeviceRequest and ConfirmRegisterDeviceResponse messages are exchanged.
Request that notifies the platform a device which wants to register. During the registration the sequence number is reset to a random value the platform is notified if the device has a light schedule, the type of the device, the device identification, and the device communicates its IP address to the platform. Also a random number is determined by the device and this 'randomDevice' should be present in the response form the platform.
Response which holds the time of the platform so the device can synchronize the time, contains location information for the device like GPS coordinates and Daylight Saving Time information. The device will sent ConfirmRegisterDeviceRequest after receiving the RegisterDeviceResponse. Also a random number is determined by the platform and this 'randomPlatform' should be present in the next request 'ConfirmRegisterDeviceRequest' by the device.
OSLP RegisterDeviceRequest sent from 'device-01' to platform:
OSLP RegisterDeviceResponse sent from platform to 'device-01':
NOTE: OSLP v0.5.1 is deprecated.
Contract for v0.5.1
The OSLP is a lightweight message based protocol. OSLP uses Google Protocol Buffers and is used for communication with SSLD devices (and device simulators). It is defined as a contract/interface. The interface defines datatypes and messages which use those data types. Google Protocol Buffers is used to generate the protocol implementations for Java (for the platform) and C/C++ (for the SSLD devices).
Open street light protocol does not use ASN.1 but Google Protocol Buffers. The main reason for this is the lack of a good quality free ASN.1 compiler for Java or C. Google Protocol Buffers offers a fast and free compiler for Java and C which produces small message sizes.
Public/private key pair
Signing of messages through Elliptic Curve DSA 256 bit
** Integrity of the message is ensured
** Sender identity is ensured
** No encryption, because content is not confidential
Replay attack prevention
Special note on Java security provider:
When both the DLMS and OSLP providers are deloyed within the same Java VM, the SunEC provider will not work properly. To workaround this issue, the SunPKCS11-NSS provider must be used for the OSLP protocol adapter. By default this provider is enabled on the development VM.
The protobuf contract for OSLP v0.5.1. For v0.5.1 port number 12121 is used.
The protobuf contract for OSLP v0.6.1. For v0.6.1 port number 12122 is used.
The requests and responses are sent using an OSLP envelope. This structure contains the following fields: securityKey, sequenceNumber, deviceId and payloadMessage. The first 3 field are byte arrays, the payloadMessage is a protobuf type which is serializable.
Contract for v0.6.1 The contract specifies the messages which can be exchanged with an SSLD.
These messages below are part of OSLP v0.6.1. Note that OSLP v0.6.1 is backwards compatible with OSLP v0.5.1. Therefore, v0.6.1 offers the same RegisterDeviceRequest as v0.5.1 for example.
RegisterDeviceRequest (from device to platform) is a request that notifies the platform a device which wants to register. During the registration the sequence number is reset to a random value, the platform is notified if the device has a light schedule, the type of the device, the device identification, and the device communicates its IP address to the platform.
RegisterDeviceResponse (from platform to device) is a response which holds the time of the platform so the device can synchronize the time, contains location information for the device like GPS coordinates and Day Light Saving time information. The device will sent ConfirmRegisterDeviceRequest after receiving the RegisterDeviceResponse.
ConfirmRegisterDeviceRequest (from device to platform) is a request that notifies the platform that a device wants to perform the second step of the registration process.
ConfirmRegisterDeviceResponse (from platform to device) is a response which confirms the ConfirmRegisterDeviceRequest has been executed or rejected.
StartSelfTestRequest (from platform to device) is a request that notifies the device to switch all relays on.
StartSelfTestResponse (from device to platform) is a response which confirms the StartSelfTestRequest has been executed or rejected.
StopSelfTestRequest (from platform to device) is a request that notifies the device to switch all relays off.
StopSelfTestResponse (from device to platform) is a response which confirms the StopSelfTestRequest has been executed or rejected.
UpdateFirmwareRequest (from platform to device) is a request which notifies the device to download a new firmware version from a server using a URL.
UpdateFirmwareResponse (from device to platform) is a response which confirms the UpdateFirmwareRequest has been executed or rejects the UpdateFirmwareRequest. Please note there are several events which are sent from the device to the platform to inform the platform when the firmware has been downloaded and whether or not the firmware was successfully activated.
SetLightRequest (from platform to device) is a request that notifies the device to switch on or off one ore several light relays, optionally with a dim-value per relay.
SetLightResponse (from device to platform) is a response which confirms the SetLightRequest has been executed or rejected.
GetStatusRequest (from platform to device) is a request that requires the device to send the status of all relays, current network link and preferred network link, the type of configuration (PSLD vs SSLD), and the event notification mask which has been set.
GetStatusResponse (from device to platform) is a response which confirms the GetStatusRequest has been executed and returns the current status for all of the relays and other information or rejects the GetStatusRequest.
ResumeScheduleRequest (from platform to device) is a request that notifies the device to continue the current schedule after the current schedule was interrupted (for example by switching by hand using SetLightRequest). This request can operate on a single relay or on all relays and the resuming of the schedule can be immediate or at the next schedule-entry.
ResumeScheduleResponse (from device to platform) is a response which confirms the ResumeScheduleRequest has been executed or rejected.
SetEventNotificationsRequest (from platform to device) is a request that sets the event notification mask.
SetEventNotificationsResponse (from device to platform) is a response which confirms the SetEventNotifications request has been executed or rejected.
EventNotificationRequest (from device to platform) is a request that pushes an event notification from a device to the platform.
EventNotificationResponse (from platform to device) is a response which confirms the EventNotificationRequest has been executed or rejected.
GetFirmwareVersionRequest (from platform to device) is a request that requests the device to sent its current firmware version.
GetFirmwareVersionResponse (from device to platform) is a response that sends the current firmware version to the platform.
SetScheduleRequest (from platform to device) is a request that sends a light or tariff schedule to the device.
SetScheduleResponse (from device to platform) is a response which confirms the SetScheduleRequest has been executed or rejected.
SetConfigurationRequest (from platform to device) is a request that sends configuration settings to the device.
SetConfigurationResponse (from device to platform) is a response which confirms the SetConfigurationRequest has been executed or rejected.
GetConfigurationRequest (from platform to device) is a request that requests the device to send its current configuration settings.
GetConfigurationResponse (from device to platform) is a response which confirms the GetConfigurationRequest has been executed or rejected.
SetRebootRequest (from platform to device) is a request that notifies the device to reboot immediately.
SetRebootResponse (from device to platform) is a response which confirms the SetRebootRequest has been executed or rejected.
SetTransitionRequest (from platform to device) is a request that notifies the device to switch its light relays according to light measurement schedule-entries.
SetTransitionResponse (from device to platform) is a response which confirms the SetTransitionRequest has been executed or rejected.
UpdateDeviceSslCertification (from platform to device) is a request which commands a device to download a new certificate file from a server using a URL.
UpdateDeviceSslCertification (from platform to device) is a response which returns the result of the UpdateFirmwareRequest. Please note there are several events which are sent from the device to the platform to inform the platform whether or not the certificate file was successfully downloaded and activated.
SetDeviceVerificationKeyRequest (from platform to device) is a request which sends a new OSGP public key to the device.
SetDeviceVerificationKeyResponse (from platform to device) is a response which returns the result of the SetDeviceVerificationKeyRequest.
SwitchFirmwareRequest (from platform to device) is a request which commands the device to switch to the other firmware bank.
SwitchFirmwareResponse (from platform to device) is a response which returns the result of the SwitchFirmwareRequest.
SwitchConfigurationRequest (from platform to device) is a request which commands the device to switch to the other configuration bank.
SwitchConfigurationResponse (from platform to device) is a response which returns the result of the SwitchConfigurationRequest.
Request which contains the 2 random numbers from RegisterDeviceRequest and RegisterDeviceResponse. The numbers should match with the previous request and response and this is checked by the platform.
Response which contains the sequenceWindow which is the maximum allowed difference between sequence numbers for future messages. Further the response contains the 2 random numbers from the ConfirmRegisterDeviceRequest. The numbers should match with the previous request and response and this is checked by the device.
OSLP ConfirmRegisterDeviceRequest sent from 'device-01' to platform:
OSLP ConfirmRegisterDeviceResponse sent from platform to 'device-01':
Request which contains the EventNotification mask.
Response communicates status.
Soap requests and responses sent to and from platform:
OSLP SetEventNotificationsRequest sent to 'device-01' to set EventNotifications:
OSLP SetEventNotificationsResponse sent to platform:
Request to fetch the current configuration of a device.
Response communicates if the request was executed. If 'status = OK' then the optional fields will be partly populated. Note that DaliConfiguration is only present for devices with 'lightType = DALI', which are of device type PSLD. Note that RelayConfiguration is only present for devices with 'lightType = RELAY | ONE_TO_TEN_VOLT | ONE_TO_TEN_VOLT_REVERSE', which are of device type SSLD.
Soap requests and responses sent to and from platform:
OSLP GetConfigurationRequest message sent to 'device-01':
OSLP GetConfigurationResponse message sent to platform:
Request to set a light or tariff schedule on a device.
Response communicates status.
Screenshot of this schedule in an OSGP client application.
SOAP Request Message for Platform web service:
SOAP Response Message:
OSLP SetScheduleRequest sent to 'device-01' to set a Light Schedule (1 page in this case, therefore no pagingInfo needed):
OSLP SetScheduleResponse from 'device-01':
Description for this schedule:
This schedule combines a 'morning/evening light' with an 'all night light'. Relay 1 and 2 will be switched on using a light measurement trigger. Relay 2 will be switched off at 23:00 using an absolute time. Relay 2 will be switched on at 07:00, but only when no light measurement trigger has been received yet. Relay 1 and 2 will be switched off using a light measurement trigger.
The first schedule-entry:
Definitions:
'index: "\000"' means: all device relays configured as LIGHT relays (see SetConfigurationRequest message)
'light measurement trigger' is defined as: a SetTransitionRequest message containing a TransitionType matching the schedule-entry's actionTime value (SUNRISE matches NIGHT_DAY and SUNSET matches DAY_NIGHT)
Specifies: For all (weekday: ALL) 7 days of the week, when a light measurement trigger is received in the morning (actionTime: SUNRISE), then all device relays configured as LIGHT relays have to switch off (on: false).
When and only when a SUNRISE transition is received via a light measurement trigger (LIGHT_TRIGGER) within a window of 15 minutesBefore and 15 minutesAfter the calculated astronomical time for sunrise, then the device shall switch for the received light measurement trigger.
When no SUNRISE transition is received via a light measurement trigger (LIGHT_TRIGGER) within a window of 15 minutesBefore and 15 minutesAfter the calculated astronomical time for sunrise, then the device shall switch at the end of the window.
The triggerType (LIGHT_TRIGGER) defines how a SUNRISE (actionTime) transition will be triggered.
The second schedule-entry:
Definitions:
'index: "\000"' means: all device relays configured as LIGHT relays (see SetConfigurationRequest message)
'light measurement trigger' is defined as: a SetTransitionRequest message containing a TransitionType matching the schedule-entry's actionTime value (SUNRISE matches NIGHT_DAY and SUNSET matches DAY_NIGHT)
Specifies: For all (weekday: ALL) 7 days of the week, when a light measurement trigger is received in the morning (actionTime: SUNSET), then all device relays configured as LIGHT relays have to switch on (on: true).
When and only when a SUNSET transition is received via a light measurement trigger (triggerType: LIGHT_TRIGGER) within a window of 15 minutesBefore and 15 minutesAfter the calculated astronomical time for sunset, then the device shall switch for the received light measurement trigger.
When no SUNSET transition is received via a light measurement trigger (triggerType: LIGHT_TRIGGER) within a window of 15 minutesBefore and 15 minutesAfter the calculated astronomical time for sunrise, then the device shall switch at the end of the window.
The triggerType (LIGHT_TRIGGER) defines how a SUNSET (actionTime) transition will be triggered.
The third schedule-entry:
Specifies: For all (weekday: ALL) 7 days of the week, when its 11 'o clock in the evening (actionTime: ABSOLUTETIME and time: "230000") then device relay 2 has to switch off (on: false).
Since actionTime is ABSOLUTETIME, the triggerType value must be omitted from this schedule-entry.
The fourth schedule-entry:
For all (weekday: ALL) 7 days of the week, when its 7 'o clock in the morning (actionTime: ABSOLUTETIME and time: "070000") and there are no other schedule-entries that have caused the switching of device relay 2 within the window defined (minutesBefore: 150 and minutesAfter) then device relay 2 has to switch on (on: true).
Since actionTime is ABSOLUTETIME, the triggerType value must be omitted from this schedule-entry.
The last element of the SetScheduleRequest:
specifies that this is a light schedule.
SOAP Request to obtain response from 'device-01':
SOAP Response containing response from 'device-01':
SOAP messages:
OSLP SetScheduleRequest sent to 'device-01' to set a Light Schedule:
OSLP SetScheduleResponse sent to platform:
Description for this schedule:
This schedule has one entry which switches light relay 1 (index: "\001") off at January 1st 2016 at 7 'o clock in the morning. When 'weekday' is set to ABSOLUTEDAY, the date will be placed in 'startDay'.
SOAP messages:
OSLP SetScheduleRequest sent to 'device-01':
OSLP SetScheduleResponse from 'device-01':
Description for this schedule:
This schedule consists of 1 page, and uses 'minimumLightOn' to indicate a minimal burning time in seconds. Further it uses 'index' and 'isEnabled' variables for the Schedule struct, to indicate what index this schedule-entry has within the list of schedule-entries and whether or not the schedule-entry is enabled.
Astronomical Offsets
The SOAP request message may contain information about astronomical offsets (see the documentation about light schedules for more details about the offsets).
When AstronomicalSunriseOffset
and/or AstronomicalSunsetOffset
are set, they will be configured on the device by updating the configuration setting the offsets as astroGateSunRiseOffset
and astroGateSunSetOffset
of the SetConfigurationRequest
.
SOAP Request Message for Platform web service:
SOAP Response Message:
OSLP SetScheduleRequest sent to 'device-01' to set a Tariff Schedule (2 pages in this case):
OSLP SetScheduleResponse from 'device-01' for page 1:
OSLP SetScheduleResponse from 'device-01' for page 2:
Description for this schedule:
This schedule defines the tariff switching moments. For most weekdays of the year the tariff is high from 7 'o clock in the morning until 11 'o clock in the evening. During the night and weekend, the tariff is low. However for certain days, like Christmas Day, the tariff has to be low as well (Christmas Day may be a weekday).
The first schedule-entry:
specifies that for every work day of the week (weekday: WEEKDAY meaning from Monday until Friday) from 1st of January 2015 until 1st of February 2016 (startDay: "20150101" and endDay: "20160201") at 11 'o clock in the evening (actionTime: ABSOLUTETIME and time: "230000") the relay with index 3 (index: "\003") has to switch on (on: true). When a device is configured to have relay 3 as TARIFF relay, this means the tariff will be low. When a device is configured to have relay 3 as TARIFF_REVERSED, this means the tariff will be high.
The second schedule-entry:
specifies that for every work day of the week (weekday: WEEKDAY meaning from Monday until Friday) from 1st of January 2015 until 1st of February 2016 (startDay: "20150101" and endDay: "20160201") at 7 'o clock in the morning (actionTime: ABSOLUTETIME and time: "070000") the relay with index 3 (index: "\003") has to switch off (on: false). When a device is configured to have relay 3 as TARIFF relay, this means the tariff will be high. When a device is configured to have relay 3 as TARIFF_REVERSED, this means the tariff will be low.
The third schedule-entry:
specifies that for every work day of the week (weekday: WEEKDAY meaning from Monday until Friday) from 1st of January 2015 until 1st of January 2015 (startDay: "20150101" and endDay: "20150101") at 7 'o clock in the morning (actionTime: ABSOLUTETIME and time: "070000") the relay with index 3 (index: "\003") has to switch on (on: true). When a device is configured to have relay 3 as TARIFF relay, this means the tariff will be low. When a device is configured to have relay 3 as TARIFF_REVERSED, this means the tariff will be high. This schedule entry is needed to make sure that the tariff is low for a particular day of the year (New Year's Day).
The fourth schedule-entry:
specifies that for every work day of the week (weekday: WEEKDAY meaning from Monday until Friday) from 6st of April 2015 until 6st of April 2015 (startDay: "20150406" and endDay: "20150406") at 7 'o clock in the morning (actionTime: ABSOLUTETIME and time: "070000") the relay with index 3 (index: "\003") has to switch on (on: true). When a device is configured to have relay 3 as TARIFF relay, this means the tariff will be low. When a device is configured to have relay 3 as TARIFF_REVERSED, this means the tariff will be high. This schedule entry is needed to make sure that the tariff is low for a particular day of the year (Easter Monday).
The fifth schedule-entry:
specifies that for every work day of the week (weekday: WEEKDAY meaning from Monday until Friday) from 27st of April 2015 until 27st of April 2015 (startDay: "20150427" and endDay: "20150427") at 7 'o clock in the morning (actionTime: ABSOLUTETIME and time: "070000") the relay with index 3 (index: "\003") has to switch on (on: true). When a device is configured to have relay 3 as TARIFF relay, this means the tariff will be low. When a device is configured to have relay 3 as TARIFF_REVERSED, this means the tariff will be high. This schedule entry is needed to make sure that the tariff is low for a particular day of the year (Dutch Kings Day).
The pagination info:
specifies that this is the first page of a total of 2 pages. The pageSize is set by the platform and can be any value from 1 to 50.
The last element of the SetScheduleRequest:
specifies that this is a tariff schedule.
The sixth schedule-entry (page 2):
specifies that for every work day of the week (weekday: WEEKDAY meaning from Monday until Friday) from 14th of May 2015 until 14th of May 2015 (startDay: "20150514" and endDay: "20150514") at 7 'o clock in the morning (actionTime: ABSOLUTETIME and time: "070000") the relay with index 3 (index: "\003") has to switch on (on: true). When a device is configured to have relay 3 as TARIFF relay, this means the tariff will be low. When a device is configured to have relay 3 as TARIFF_REVERSED, this means the tariff will be high. This schedule entry is needed to make sure that the tariff is low for a particular day of the year (Ascension Day).
The seventh schedule-entry (page 2):
specifies that for every work day of the week (weekday: WEEKDAY meaning from Monday until Friday) from 25th of May 2015 until 25th of May 2015 (startDay: "20150525" and endDay: "20150525") at 7 'o clock in the morning (actionTime: ABSOLUTETIME and time: "070000") the relay with index 3 (index: "\003") has to switch on (on: true). When a device is configured to have relay 3 as TARIFF relay, this means the tariff will be low. When a device is configured to have relay 3 as TARIFF_REVERSED, this means the tariff will be high. This schedule entry is needed to make sure that the tariff is low for a particular day of the year (Whit Monday).
The eighth schedule-entry (page 2):
specifies that for every work day of the week (weekday: WEEKDAY meaning from Monday until Friday) from 25th of December 2015 until 25th of December 2015 (startDay: "20151225" and endDay: "20151225") at 7 'o clock in the morning (actionTime: ABSOLUTETIME and time: "070000") the relay with index 3 (index: "\003") has to switch on (on: true). When a device is configured to have relay 3 as TARIFF relay, this means the tariff will be low. When a device is configured to have relay 3 as TARIFF_REVERSED, this means the tariff will be high. This schedule entry is needed to make sure that the tariff is low for a particular day of the year (Christmas Day).
The ninth schedule-entry (page 2):
specifies that for every work day of the week (weekday: WEEKDAY meaning from Monday until Friday) from 1st of January 2016 until 1st of January 2016 (startDay: "20160101" and endDay: "20160101") at 7 'o clock in the morning (actionTime: ABSOLUTETIME and time: "070000") the relay with index 3 (index: "\003") has to switch on (on: true). When a device is configured to have relay 3 as TARIFF relay, this means the tariff will be low. When a device is configured to have relay 3 as TARIFF_REVERSED, this means the tariff will be high. This schedule entry is needed to make sure that the tariff is low for a particular day of the year (New Year's Day).
The pagination info (page 2):
specifies that this is the second page of a total of 2 pages. The pageSize is set by the platform and can be any value from 1 to 50.
The last element of the SetScheduleRequest:
specifies that this is a tariff schedule.
SOAP Request to obtain response from 'device-01':
SOAP Response containing response from 'device-01':
Request which notifies the device to reboot immediately. After a reboot, the device will switch its relays according to its schedule. Any ad hoc changes to relays will be lost.
Response communicates status.
Soap requests and responses sent to and from platform:
OSLP SetRebootRequest message sent to 'device-01':
OSLP SetRebootResponse sent to platform:
Request that notifies the device to switch all light relays off.
Response communicates status and the result of the test.
Soap requests and responses sent to and from platform:
OSLP StopSelfTestRequest sent to 'device-01':
OSLP StopSelfTestResponse sent to platform:
Request which notifies the device to send the current firmware version.
Response containing the firmware version.
Soap requests and responses sent to and from platform:
OSLP GetFirmwareRequest message sent to 'device-01':
OSLP GetFirmwareResponse message sent to platform:
Request that notifies the device to continue the current schedule after the current schedule was interrupted (for example by switching by hand using SetLightRequest). This request can operate on a single relay or on all relays and the resuming of the schedule can be immediate or at the next schedule-entry.
Response which confirms the ResumeScheduleRequest has been executed or rejects the ResumeScheduleRequest.
Soap requests and responses sent to and from platform:
OSLP ResumeScheduleRequest sent to 'device-01':
OSLP ResumeScheduleResponse sent to platform:
Request for a device to download and install new firmware. The request contains a URL defining the location of the new firmware image. The device should download the firmware from that location.
Response communicates status.
Soap requests and responses sent to and from platform:
OSLP UpdateFirmwareRequest sent to 'device-01' to update firmware:
OSLP UpdateFirmwareResponse sent to the platform:
Request which informs a device of a daylight transiton: it has become dark (sunset) or light (sunrise). The device will switch the relays, which have schedule entries for transition messages. The optional 'time' value can be used to indicate a switch time. If the optional 'time' value is omitted the device should switch immediately. See for more information regarding switch schedules.
Response communicates status.
Soap requests and responses sent to and from platform:
OSLP SetTransitionRequest sent to 'device-01':
OSLP SetTransitionResponse sent to platform:
Request that notifies the device to switch on or off one or several light relays, optionally with a dim-value per relay. If optional value 'index' is omitted, all relays configured as light are switched. In that case, all light relays will switch using only 1 LightValue instance for 'values'. In case the value 'index' is included, multiple instances of LightValue can be used (up to 6), each indicating a particular relay. If optional value 'dimValue' is omitted, then default values of 0 and 100 will be assumed for either 'on = false' or 'on = true'.
Response communicates status.
Soap requests and responses sent to and from platform:
OSLP SetLightRequest sent to 'device-01':
OSLP SetLightResponse sent to platform:
Request that requires the device to send the status of all relays, current network link and preferred network link, the type of configuration (PSLD vs SSLD), and the event notification mask which has been set. Further, many optional values can be set by the device, like serial number, MAC address, memory sizes, current firmware version, current IP address, etc.
Response which confirms the GetStatusRequest has been executed and returns the current status for all of the relays and other information or rejects the GetStatusRequest.
Soap requests and responses sent to and from platform:
OSLP GetStatusRequest sent to 'device-01':
OSLP GetStatusResponse sent to platform:
Request to switch to a new Platform public key used for verifying OSLP envelopes by the device. The base-64 encoded version of the key will be sent to the device, which is equivalent to the content of a PEM file (only the certificate chunk, not the headers).
Soap requests and responses sent to and from platform:
OSLP messages: