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
Note: 
  • 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 RscVariant returned 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.

  • 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 updateType parameter has to be set to 0. 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: Undefined
1: ProgrammableLogicController
2: BusCoupler
3: 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 FirmwareBuildDate
ISO 8601 format <YYYY>-<MM>-<DD>
General.Firmware.BuildTime String FirmwareBuildTime
ISO 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 Mac parameter indicates the MAC address of the selected network interface.

adapterIndex: 1, 2,...

port = 0 for the interfaceMAC

port = 1, 2,... for the portMAC

MAC data format is alwaysAA:BB:CC:DD:EE:FF .

 

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):

 

These possible settings are supported:

Parameter

Data type

Description

General.Function

String

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: 0x20 .. 0x7e

Max. string length: 32 characters.

General.Location

String

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: 0x20 .. 0x7e

Max. string length: 32 characters.

Interfaces.Ethernet.{AdapterIndex}.IpAssign

Byte

AdapterIndex: 1, 2, ...

IpAssign is the configuration type of the network adapter’s IP Address.  Values are:

  • 0: Static
  • 2: DHCP

Default: 0

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 Static then the values of Ip and Subnet are taken.

Error values:

  • UnknownSetting: The AdapterIndex parameter is not supported.
  • InvalidParameter: Value is illegal.
  • IncompatibleType: Parameter is not of type Byte.

Interfaces.Ethernet.{AdapterIndex}.Ip

String

AdapterIndex: 1, 2, ...

Ip is the IP Address of a network adapter. Format: aaa.bbb.ccc.ddd where each value must contain decimal numbers between 0..255

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:

  • IncompatibleType: Value is not a String.
  • InvalidFormat: Value does not correspond to the defined format.
  • OutOfRange: At least one value is larger than 255.
  • UnknownSetting: The AdapterIndex parameter is not supported.

Interfaces.Ethernet.{AdapterIndex}.Subnet

String

AdapterIndex = 1, 2, ...

Subnet is the subnet of a network adapter. Format: aaa.bbb.ccc.ddd where each value must contain decimal numbers between 0..255

The value becomes active after a restart of the device.

Error values:

  • IncompatibleType: Value is not a String.
  • InvalidFormat: Value does not correspond to the defined format.
  • OutOfRange: At least one value is larger than 255.
  • UnknownSetting: The AdapterIndex parameter is not supported.

Interfaces.Ethernet.{AdapterIndex}.DefaultGateway

String

AdapterIndex = 1, 2, ...

DefaultGateway is the default gateway of a network adapter. Format: aaa.bbb.ccc.ddd where each value must contain decimal numbers between 0..255

The value becomes active after a restart of the device.

Error values:

  • IncompatibleType: Value is not a String.
  • InvalidFormat: Value does not correspond to the defined format.
  • OutOfRange: At least one value is larger than 255.
  • UnknownSetting: The AdapterIndex parameter is not supported.

Interfaces.Ethernet.{AdapterIndex}.DnsNameservers

String

AdapterIndex = 1, 2, ...

The DnsNameservers parameter contains a list of one or up to three DNS server names. If the list contains more than one name then they must be separated by a space character.

Format:

aaa.bbb.ccc.ddd[ eee.fff.ggg.hhh.iii][jjj.kkk.lll.mmm]

where each value must contain decimal numbers between 0..255

Default value: 8.8.8.8 8.8.4.4

Error values:

  • IncompatibleType: Value is not a String.
  • InvalidFormat: Value does not correspond to the defined format
  • OutOfRange: At least one value is larger than 255.
  • UnknownSetting: The AdapterIndex parameter is not supported

Ntp.NtpServers

String

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:serverID[ serverID]...

Example:127.127.1.0 ntp.server1.com

Max. string length: 253 characters.
Note: By writing NTP Server configuration with this service, dedicated NTP settings like min./max. polling times that have been configured via the Date and Time WBM page are removed.

Rtc.DateTime

String

Date and time of the controller

ISO 8601 format: <YYYY>-<MM>-<DD>T<hh>:<mm>:<ss>+-<hh>:<mm>

Note: Currently, a given time zone is ignored when writing this string. When reading, +00:00 is responded.

Rtc.Time

String

Time of the controller

ISO 8601 format: <hh>:<mm>:<ss>

Rtc.Date

String

Date of the controller

ISO 8601 format: <YYYY>-<MM>-<DD>

RemovableStorage.1.State

String

Status of an external SD card. 

Note: Setting a status is only possible with admin user role.

Supported values for writing, done with a WriteValue() or WriteValues() function:

  • request_deactivation
  • request_activation

A restart is required to finalize the procedure.

Read can return following status:

  • activated: The external SD card is activated.
  • deactivated: The external SD card is deactivated.
  • request_deactivation: The deactivation is requested, a restart is required.
  • request_activation: The activation is requested, a restart is required.
  • not_supported: The setting is not supported on this device.

General.Watchdog.Plc.Restart

Byte

Definition of the behavior of the Plc component of the PLCnext Runtime after a system watchdog occurred.

0: The Plc component of the PLCnext Runtime will not restart (see 

1: The Plc component of the PLCnext Runtime will restart automatically

Default is 0.
Switching is done by means of the RSC Device Interface Services.

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:
  • TCP/IP (LAN 1)
    • Port X1
    • Port X2
Internal interfaces:
  • TCP/IP (LAN 1)
    • Interface no. = 1
External interfaces via left-aligning (AXC F 2152 only):
  • TCP/IP (EXT LAN 1)
    • Port X1
External interfaces via left-aligning:
  • TCP/IP (EXT LAN 1) - switched mode
    • Interface no. = 2
AXC F 3152 Internal interfaces:
  • TCP/IP (LAN 1)
    • Port X1
  • TCP/IP (LAN 2)
    • Port X2
  • TCP/IP (LAN 3)
    • Port X3
Internal interfaces:
  • TCP/IP (LAN 1)
    • Interface no. = 1
  • TCP/IP (LAN 2)
    • Interface no. = 2
  • TCP/IP (LAN 3)
    • Interface no. = 3
External interfaces via left-aligning:
  • TCP/IP (EXT LAN 1)
    • Port X1
External interfaces via left-aligning:
  • TCP/IP (EXT LAN 1)
    • Interface no. = 4
RFC 4072s Internal interfaces:
  • TCP/IP (LAN 1)
    • Port LAN 1
  • TCP/IP (LAN 2)
    • Port LAN 2
  • TCP/IP (LAN 3) - Switched Mode
    • Port LAN 3.1
    • Port LAN 3.2
Internal interfaces:
  •  
  • TCP/IP (LAN 1)
    • Interface no. = 1
  • TCP/IP (LAN 2)
    • Interface no. = 2
  • TCP/IP (LAN 3) - Switched Mode
    • Interface no. = 3

 

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 the deviceStatusService.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
Status.Cpu.{Core}.Load.Percent Byte

The CPU.{Core}.Load status indicates the processor load of the selected processor core of the device as a percentage. Cores are identified by numbers 1 and higher while Core 0 indicates the entire processor load.

Core:  0, 1, 2, ...

Value range:
0% ... 100% where 100% would be reported as 0x64

Status.Memory.Usage.Percent Byte The Memory.Usage status indicates the complete memory usage of the device as a percentage.
Value range:
0% ... 100% where 100% would be reported as 0x64
Status.ProgramMemoryIEC.Usage.Percent Byte The ProgramMemoryIEC.Usage status indicates the program memory usage of the IEC runtime of the device as a percentage.
Value range:
0% ... 100% where 100% would be reported as 0x64
Status.DataMemoryIEC.Usage.Percent Byte The DataMemoryIEC.Usage status indicates the data memory usage of the IEC runtime of the device as a percentage.
Value range:
0% ... 100% where 100% would be reported as 0x64
Status.RetainMemory.Usage.Percent Byte The RetainMemory.Usage status indicates the retain memory usage of the device as a percentage.
Value range:
0% ... 100% where 100% would be reported as 0x64
Status.Board.Temperature.Centigrade

Int8

The Board.Temperature status indicates the temperature of the interior of the device in °C.
Status.Board.Humidity Byte The Board.Humidity status indicates the relative humidity in the device.
Value range:
0% ... 100% where 100% would be reported as 0x64
Status.Cpu.Temperature.Centigrade

Int8

For RFC 4072S only:
TheCPU.Temperature status indicates the temperature of the processor in °C.
Status.Overlay.BootDevice String

The Overlay.BootDevice status indicates the mounting of the overlay file system. 

Values:

  • internalSD 
  • externalSD
Status.RemovableStorage.1.Present Bool

The RemovableStorage.1.Present status indicates whether an external SD card  is present. 

Values:

  • true: SD card present 
  • false: No SD card present 
Status.RemovableStorage.1.State String

TheRemovableStorage.1.State status indicates the state of the external SD card. 

Values:

  • activated: The external SD card is activated.
  • deactivated: The external SD card is deactivated.
  • request_deactivation: The deactivation is requested, a restart is required. 
  • request_activation: The activation is requested, a restart is required.
  • not_supported: The setting is not supported on this device.
Status.Fan.Supported Bool

TheFan.Supported status indicates whether the PLCnext controller supports a fan.

Values:

  • true: Fan is supported. 
  • false: Fan is not supported.

For most controllers a fan is optional. Only ifFan.Supported is true the other Fan status indicators are supported (see next rows in this table).

Status.Fan.Plugged Bool

TheFan.Plugged status indicates whether a fan is plugged. 

Values:

  • true: A fan is plugged.
  • false: No fan is plugged. 
Status.Fan.Defect Bool

TheFan.Defect status indicates whether the fan is defect. 

Values:

  • true: The fan is defect.
  • false: The fan is OK. 
Status.Fan.Maintenance Bool

TheFan.Maintenance status indicates whether the fan needs to be maintained. 

Values:

  • true: The fan needs maintenance.
  • false: No maintenance required. 
Status.Fan.Speed.Level UInt8

TheFan.Speed.Level status indicates the speed of the fan. 

Values:

  • 128: Off
  • 231: Low
  • 242: Medium
  • 255: High
Status.Fan.Timestamp String

TheFan.Timestamp status indicates date and time when the fan was calibrated the last time. 

Format:DD.MM.YYYY hh:mm

Status.RamDisk.{RamDiskIndex}.Usage.Percent Byte

For RFC 4072S only:

TheRamDisk.{RamDiskIndex}.Usage.Percent status indicates the memory usage of the RAM disc(s) as a percentage.

Value range:
0% ... 100% where 100% would be reported as0x64

RamDiskIndex = 1, 2, ... indicating the index of the RAM disc; currently, only one RAM disc is supported, so that the index is always1.

Status.RamDisk.{RamDiskIndex}.Usage UInt32

For RFC 4072S only:

TheRamDisk.{RamDiskIndex}.Usage status indicates the absolute memory usage of the RAM disc(s).
RamDiskIndex = 1, 2, ... indicating the index of the RAM disc; currently, only one RAM disc is supported, so that the index is always1.

Status.Ups.ChargeLevel Int32

From firmware release 2022.6 for PLCnext Control devices with an integrated UPS:

The Ups.ChargeLeveln status indicates the current charge status of the UPS in % (relative state of charge).

Status.Ups.Health Int32 

From firmware release 2022.6 for PLCnext Control devices with an integrated UPS:

The Ups.Health status indicates the content of the safety status register of the UPS controller. The bits HWARN and HFAIL contained in the safety status register are evaluated and the result is provided as int32 value.

  • OK: 0
  • HWARN: 1
  • HFAIL: 2
Status.Ups.Diagnostics String 

From firmware release 2022.6 for PLCnext Control devices with an integrated UPS:

The UPS.Diagnostics status indicates the current charge status of the UPS in % and the content of the UPS controller`s safety status register. The bits contained in the safety status register are evaluated in the same way as with the service Status.UPS.Health. The return values are provided in a string, divided by a blank. 

Example:  

  • UPS charge status is 75 % and HWARN is set:
    75 1
  • UPS charge status is 75 % and HFAIL is set:
    75 2

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
Status.Interfaces.Ethernet.{adapterIndex}.{port}.Baudrate Byte

adapterIndex = 1, 2, ...
port = 1, 2, ...

The Baudrate status indicates the current speed of the interface:
1: 10 Mbps
2: 100 Mbps
3: 1000 Mbps

Status.Interfaces.Ethernet.{adapterIndex}.{port}.Duplex Byte

adapterIndex: 1, 2, ...
port: 1, 2, ...

The Duplex status indicates the current duplex mode of the interface:
1: half duplex
2: full duplex

Status.Interfaces.Ethernet.{adapterIndex}.{port}.Link Byte

adapterIndex: 1, 2, ...
port: 1, 2, ...

The Link status indicates the link status of the interface:
0: linkDown
1: linkUp

Interfaces.Ethernet.{AdapterIndex}.Ip  String 

AdapterIndex: 1, 2, ...

Ip is the address of the network adapter.

Format:
aaa.bbb.ccc.ddd where each value must contain decimal numbers between 0..255 

The value is stored permanently. When the value is read then the last written value is returned. 

Note: While the IDeviceSettingsService reads the IP settings from the Interfaces file,
the IDeviceStatusService reads the current values from the interface!

Error values: 

  • IncompatibleType: Value is not a String.
  • InvalidFormat: Value does not correspond to the defined format.
  • OutOfRange: At least one value is larger than 255.
  • UnknownSetting: The AdapterIndex parameter is not supported.
Interfaces.Ethernet.{AdapterIndex}.Subnet  String

AdapterIndex: 1, 2, ...

Subnet is the subnet mask of a network adapter.

Format:
aaa.bbb.ccc.ddd where each value must contain decimal numbers between 0..255.

Error values: 

  • IncompatibleType: Value is not a String.
  • InvalidFormat: Value does not correspond to the defined format.
  • OutOfRange: At least one value is larger than 255.
  • UnknownSetting: The AdapterIndex parameter is not supported.
Interfaces.Ethernet.{AdapterIndex}.DefaultGateway  String

AdapterIndex: 1, 2, ...

DefaultGateway is the default gateway of a network adapter.

Format:
aaa.bbb.ccc.ddd where each value must contain decimal numbers between 0..255.

Error values: 

  • IncompatibleType: Value is not a String.
  • InvalidFormat: Value does not correspond to the defined format.
  • OutOfRange: At least one value is larger than 255.
  • UnknownSetting: The AdapterIndex parameter is not supported.

 

 

 


•  Web browser recommendation: Chrome/Edge 88 or newer, Firefox ESR 90 or neweror Safari • 
• Published/reviewed: 2022-09-14 • Revision 046 •