RSC Device Interface Services
The RSC Device Interface Services provide a range of functions for accessing properties of the operating system and the controller hardware. You can call the information with the following interfaces and defined parameters. The following headers are required to use the service; integrate these headers via #include, if necessary:
- Arp\Device\Interface\Services\IDeviceControlService.hpp
- Arp\Device\Interface\Services\IDeviceInfoService.hpp
- Arp\Device\Interface\Services\IDeviceSettingsService.hpp
- Arp\Device\Interface\Services\IDeviceStatusService.hpp
- Execution of RSC services can take some time. For this reason, avoid direct calls from ESM tasks.
- Exceptions thrown by RSC service calls should always be explicitly caught and handled by RSC clients.
- In addition, the underlying type of each
RscVariantreturned by RSC service calls should never be assumed but should always be checked before performing any other operation on that object.
IDeviceControlService
TheIDeviceControlService RSC interface provides the following methods to control the device:
-
void RestartDevice ();This method reboots the PLC.
Note: T must not be invoked within an ESM task. -
AccessErrorCode ResetToFactoryDefaults (Uint16 resetType);With
resetType == 1:
All user-specific data is deleted (settings, programs, users, etc.). The current PLCnext Technology firmware remains unchanged.With
resetType == 2:
In addition to deleting the user-specific data, the firmware of the controller is reset to the default state. -
AccessErrorCode StartFirmwareUpdate (Uint16 updateType);This function starts to update the firmware using a previously downloaded firmware container. The
updateTypeparameter has to be set to0. Other values are reserved for future extensions.
IDeviceInfoService
The IDeviceInfoService RSC interface enables read access to device information with the following methods:
-
RscVariant<512> GetItem(const RscString<512>& identifier)The
GetItem()method reads the status value of a parameter. -
void GetItems(GetItemsIdentifiersDelegate identifiersDelegate, GetItemsResultDelegate resultDelegate)The
GetItems()method reads the status values of several parameters.
The following parameters are available in the IDeviceInfoService RSC interface for calling of information:
| Parameter | Data type | Description |
General.DeviceClass |
UInt32 |
The DeviceClass parameter specifies the device class. At the moment, only ProgrammableLogicController is supported.0: Undefined1: ProgrammableLogicController2: BusCoupler3: Switch
|
General.VendorName |
String |
The VendorName parameter indicates the name of the manufacturer. |
General.ArticleName |
String |
The ArticleName parameter indicates the device name. |
General.ArticleNumber |
String |
The ArticleNumber parameter indicates the order number of the device. |
General.SerialNumber |
String |
The SerialNumber parameter indicates the serial number of the device. |
General.CloudUuid |
String |
The CloudUuid parameter indicates the Proficloud UUID of the device |
General.Firmware.Version |
String |
The FirmwareVersion parameter indicates the firmware version of the device. Here, the 5-level notation (Major, Minor, Patch, Build, Status) is used. |
General.Firmware.VersionMajor |
Byte |
The firmware version year is indicated without the first two digits. E.g., “2019” is indicated as 19. |
General.Firmware.VersionMinor |
Byte |
FirmwareVersionMinor |
General.Firmware.VersionPatch |
Byte |
FirmwareVersionPatch |
General.Firmware.VersionBuild |
UInt32 |
FirmwareVersionBuild |
General.Firmware.VersionStatus |
String |
FirmwareVersionStatus |
General.Firmware.BuildDate |
String |
FirmwareBuildDateISO 8601 format <YYYY>-<MM>-<DD> |
General.Firmware.BuildTime |
String |
FirmwareBuildTimeISO 8601 format <hh>:<mm>:<ss> |
General.Hardware.Version |
String |
The HardwareVersion parameter indicates the hardware version of the device. |
General.Fpga.Version |
String |
The FPGAVersion parameter indicates the FPGA version of the device. Here, the 3-level notation (Major, Minor, Patch) is used. |
General.Fpga.VersionMajor |
Byte |
FPGAVersionMajor |
General.Fpga.VersionMinor |
Byte |
FPGAVersionMinor |
General.Fpga.VersionPatch |
Byte |
FPGAVersionPatch |
General.UniqueHardwareId |
String |
Sha256 Hash (32byte) hexadecimal coded as string |
General.SPNS.Fpga.Version |
String |
FPGA version of the SPNS (only for devices with integrated safety controller) |
General.SPNS.Fpga.VersionMajor |
Byte |
SPNS FPGA version, major |
General.SPNS.Fpga.VersionMinor |
Byte |
SPNS FPGA version, minor |
General.SPNS.Fpga.BuildVersion |
Unsigned32 |
SPNS FPGA build version |
General.SPNS.Firmware.Version |
String |
SPNS firmware version |
General.SPNS.Firmware.VersionMajor |
Byte |
SPNS firmware version, major |
General.SPNS.Firmware.VersionMinor |
Byte |
SPNS firmware version, minor |
General.SPNS.Firmware.BuildVersion |
Unsigned32 |
SPNS firmware build version |
Interfaces.Ethernet.Count |
Byte |
The NoOfNetworkInterfaces parameter indicates the number of network interfaces. |
Interfaces.Ethernet.{adapterIndex}.{port}.Mac |
String |
The
|
Cpu.Cores.Count |
Byte |
From firmware version 2023.0 LTS: The parameter |
IDeviceSettingsService
With the IDeviceSettingsService, several settings of the device can be read or written.
Therefore, this service provides four methods (linked to the related description in the 2022.0 LTS API documentation):
- Read a single setting:
DeviceSettingResult ReadValue (const RscString< 512 > &setting); - Read a list of settings:
void ReadValues (ReadValuesSettingsDelegate settingsDelegate, ReadValuesResultDelegate resultDelegate) - Write a single setting:
AccessErrorCode WriteValue (const DeviceSettingItem &settingItem) - Write a list of settings:
void WriteValues (WriteValuesSettingItemsDelegate settingItemsDelegate, WriteValuesResultDelegate resultDelegate)
These possible settings are supported:
|
Parameter |
Data type |
Description |
|
|
|
Function description appropriate to the PROFINET specification. The parameter is retained in the I&M2 data and still available after a firmware update. (Projects/Default/Device/Interface/Di.User.config). Valid characters: Max. string length: 32 characters. |
|
|
|
Installation location of a device appropriate to the PROFINET specification. The parameter is retained in the I&M2 data and still available after a firmware update. (Projects/Default/Device/Interface/Di.User.config) Valid characters: Max. string length: 32 characters. |
|
|
|
Default: Note: DHCP only works on adapters without PROFINET function (for settings, see the respective hardware documentation). The value becomes active after a restart of the device. If the value is Error values:
|
|
|
|
The value becomes active after a restart of the device. The value is stored permanently. When the value is read then the last written value is returned. Error values:
|
|
|
|
The value becomes active after a restart of the device. Error values:
|
|
|
|
DefaultGateway is the default gateway of a network adapter. Format: The value becomes active after a restart of the device. Error values:
|
|
|
|
The Format:
where each value must contain decimal numbers between Default value: Error values:
|
|
|
|
List of all NTP servers. The server can be defined as IP address or in DNS format. The list should always contain the list of all NTP servers, otherwise the list on the device is incomplete. If the parameter contains an empty string, then all servers are deleted except the fallback server. Format: Example: Max. string length: 253 characters. |
|
|
|
Date and time of the controller ISO 8601 format: Note: Currently, a given time zone is ignored when writing this string. When reading, |
|
|
|
Time of the controller ISO 8601 format: |
|
|
|
Date of the controller ISO 8601 format: |
|
|
|
Status of an external SD card. Note: Setting a status is only possible with Supported values for writing, done with a
A restart is required to finalize the procedure. Read can return following status:
|
|
|
|
Definition of the behavior of the
Default is |
Error codes
The values of AccessErrorCode and their meanings are:
| Value | Code |
None |
0 |
UnknownError |
1 |
UnknownSetting |
2 |
AuthorizationFailure |
3 |
IncompatibleType |
4 |
InvalidFormat |
5 |
InvalidParameter |
6 |
OutOfRange |
7 |
Naming of LAN interfaces and LAN ports on controllers
The following table provides an overview to the different PLCnext Control devices and the naming of their LAN interfaces and ports. The naming of a port is the same as printed on the housing, e.g. X1.
| PLCnext Control | Naming on the housing | Interface no. in IDeviceSettingsService |
| AXC F 2152 AXC F 1152 |
Internal interfaces:
|
Internal interfaces:
|
External interfaces via left-aligning (AXC F 2152 only):
|
External interfaces via left-aligning:
|
|
| AXC F 3152 | Internal interfaces:
|
Internal interfaces:
|
External interfaces via left-aligning:
|
External interfaces via left-aligning:
|
|
| RFC 4072s | Internal interfaces:
|
Internal interfaces:
|
IDeviceStatusService
The IDeviceStatusService RSC interface enables read access to status information.
-
The status value of a parameter is read with the
GetItem()method.RscVariant<512> GetItem(const RscString<512>& identifier) -
The status values of several parameters are read with the
GetItems()method. Use thedeviceStatusService.GetItem("Parameters")method to call status information.void GetItems(GetItemsIdentifiersDelegate identifiersDelegate, GetItemsResultDelegate resultDelegate)
The following parameters are available for calling information:
| Parameter | Data type | Description |
|
|
|
The
Value range:
|
|
|
|
The Value range:
|
|
|
|
The Value range:
|
|
|
|
The Value range: |
|
|
|
The Value range: |
|
|
|
The Value range:
|
|
|
|
The |
|
|
|
The Value range:
|
|
|
|
For RFC 4072S only: |
|
|
|
The Values:
|
|
|
|
The Values:
|
|
|
|
The Values:
|
|
|
|
The Values:
For most controllers a fan is optional. Only if |
|
|
|
The Values:
|
|
|
|
The Values:
|
Status.Fan.Maintenance |
Bool |
The Values:
|
|
|
|
The Values:
|
|
|
|
The Format: |
|
|
|
For RFC 4072S only: Value range:
|
|
|
|
For RFC 4072S only: |
|
|
|
From firmware release 2022.6 for PLCnext Control devices with an integrated UPS: The |
|
|
|
From firmware release 2022.6 for PLCnext Control devices with an integrated UPS: The Values:
|
|
|
|
From firmware release 2022.6 for PLCnext Control devices with an integrated UPS: The The return values are provided in a string, divided by a blank. Examples:
|
|
|
|
From firmware version 2023.0 LTS: The status service This service is only available if the device supports a mode selector switch. This can be queried with the status service Return values:
|
|
|
|
From firmware version 2023.0 LTS: The status service Return values:
|
|
|
|
From firmware version 2023.0 LTS for RFC 4072R only: The RFC 4072R as a dedicated redundancy controller is equipped with redundant power supplies. Return values for each X1 and X2:
|
You can also call status information about the LED states via the IDeviceStatusService interface.
The colors of the LEDs are represented as follows, normally in the high word (HW) of the return value:
public enum LedColor : ushort
{
Green = 1,
Yellow = 2,
Red = 4
};The status of the LEDs is represented as follows, normally in the low word (LW) of the return value:
public enum LedStates : ushort
{
Off = 0,
On = 1,
Flashing_0_5_Hz = 2,
Flashing_2_Hz = 3,
Alternating_0_5_Hz = 4,
Alternating_2_Hz = 5
};IEC runtime system LEDs
| Parameter | Data type | Description |
Status.Leds.Runtime.Run |
UInt32 |
Runtime RUN LED (HW: color, LW: status) |
Status.Leds.Runtime.Fail |
UInt32 |
Runtime FAIL LED (HW: color, LW: status) |
Status.Leds.Runtime.Debug |
UInt32 |
Runtime DEBUG LED (HW: color, LW: status) |
Axioline LEDs
| Parameter | Data type | Description |
Status.Leds.Axio.D |
UInt32 |
AXIO master D LED (HW: color, LW: status) |
Status.Leds.Axio.E |
UInt32 |
AXIO master E LED (HW: color, LW: status) |
PROFINET LEDs
| Parameter | Data type | Description |
Status.Leds.Pnio.Bf_C |
UInt32 |
Pnio controller BF LED (HW= color, LW= status) |
Status.Leds.Pnio.Bf_D |
UInt32 |
Pnio device BF LED (HW= color, LW= status) |
Status.Leds.Pnio.Sf |
UInt32 |
Pnio controller SF LED (HW= color, LW= status) |
Calling network status information via IDeviceStatusService
You can also call status information about the network states via the IDeviceStatusService interface:
| Parameter | Data type | Description |
|
|
|
The |
|
|
|
The |
|
|
|
The |
|
|
|
Format: The value is stored permanently. When the value is read then the last written value is returned. Note: While the Error values:
|
|
|
|
Format: Error values:
|
|
|
|
Format: Error values:
|
See also