SLMP Python API Reference
This page is generated during the docs-site build from the installed plc-comm-slmp PyPI package.
It follows the latest package release installed by the site build. Use the handwritten Getting started and Usage guide pages for task-oriented examples, and this page for the complete public Python API surface.
Operation Index
The sync SlmpClient and async AsyncSlmpClient expose the same low-level
operation names unless noted otherwise.
Direct And Random Device Operations
| Operation | Public API |
|---|---|
| Direct device read/write | read_devices, write_devices |
| 32-bit values | read_dword, write_dword, read_dwords, write_dwords |
| Float32 values | read_float32, write_float32, read_float32s, write_float32s |
| Extended direct device read/write | read_devices_ext, write_devices_ext |
| Random read | read_random |
| Extended random read | read_random_ext |
| Random word/dword write | write_random_words |
| Extended random word/dword write | write_random_words_ext |
| Random bit write | write_random_bits |
| Extended random bit write | write_random_bits_ext |
| Block read/write | read_block, write_block |
| Type name | read_type_name |
Extended random APIs use the 008x subcommands. Use qualified device notation
such as U1\G0, U3E0\HG0, or J2\SW10 where the route requires it.
Specialized Operations
| Operation | Public API |
|---|---|
| Monitor registration/cycle | register_monitor_devices, register_monitor_devices_ext, run_monitor_cycle |
| Memory command words | memory_read_words, memory_write_words |
| Extend-unit command words | extend_unit_read_words, extend_unit_write_words |
| Label array access | read_array_labels, write_array_labels |
| Label random access | read_random_labels, write_random_labels |
| Remote CPU control | remote_run, remote_stop, remote_pause, remote_latch_clear, remote_reset |
| Remote password | remote_password_unlock, remote_password_lock |
| Self-test loopback | self_test_loopback |
| Clear Error | clear_error |
High-Level Helpers
| Operation | Public API |
|---|---|
| Connection helper | open_and_connect, open_and_connect_sync |
| Typed values | read_typed, write_typed |
| Named mixed snapshots | read_named, write_named, poll |
| Single-request word/dword reads | read_words_single_request, read_dwords_single_request |
| Address handling | normalize_address, parse_address, try_parse_address, format_address |
| Bit-in-word write | write_bit_in_word |
Generated API Details
slmp
SLMP client library with high-level helpers as the recommended user surface.
The primary user-facing entry points are:
read_typed/write_typedread_words_single_request/read_dwords_single_requestwrite_bit_in_wordread_named/write_namedpoll
DEVICE_CODES = {'SM': DeviceCode(145, 10, DeviceUnit.BIT), 'SD': DeviceCode(169, 10, DeviceUnit.WORD), 'X': DeviceCode(156, 16, DeviceUnit.BIT), 'Y': DeviceCode(157, 16, DeviceUnit.BIT), 'M': DeviceCode(144, 10, DeviceUnit.BIT), 'L': DeviceCode(146, 10, DeviceUnit.BIT), 'F': DeviceCode(147, 10, DeviceUnit.BIT), 'V': DeviceCode(148, 10, DeviceUnit.BIT), 'B': DeviceCode(160, 16, DeviceUnit.BIT), 'S': DeviceCode(152, 10, DeviceUnit.BIT), 'D': DeviceCode(168, 10, DeviceUnit.WORD), 'W': DeviceCode(180, 16, DeviceUnit.WORD), 'TS': DeviceCode(193, 10, DeviceUnit.BIT), 'TC': DeviceCode(192, 10, DeviceUnit.BIT), 'TN': DeviceCode(194, 10, DeviceUnit.WORD), 'LTS': DeviceCode(81, 10, DeviceUnit.BIT), 'LTC': DeviceCode(80, 10, DeviceUnit.BIT), 'LTN': DeviceCode(82, 10, DeviceUnit.WORD), 'STS': DeviceCode(199, 10, DeviceUnit.BIT), 'STC': DeviceCode(198, 10, DeviceUnit.BIT), 'STN': DeviceCode(200, 10, DeviceUnit.WORD), 'LSTS': DeviceCode(89, 10, DeviceUnit.BIT), 'LSTC': DeviceCode(88, 10, DeviceUnit.BIT), 'LSTN': DeviceCode(90, 10, DeviceUnit.WORD), 'CS': DeviceCode(196, 10, DeviceUnit.BIT), 'CC': DeviceCode(195, 10, DeviceUnit.BIT), 'CN': DeviceCode(197, 10, DeviceUnit.WORD), 'LCS': DeviceCode(85, 10, DeviceUnit.BIT), 'LCC': DeviceCode(84, 10, DeviceUnit.BIT), 'LCN': DeviceCode(86, 10, DeviceUnit.WORD), 'SB': DeviceCode(161, 16, DeviceUnit.BIT), 'SW': DeviceCode(181, 16, DeviceUnit.WORD), 'DX': DeviceCode(162, 16, DeviceUnit.BIT), 'DY': DeviceCode(163, 16, DeviceUnit.BIT), 'Z': DeviceCode(204, 10, DeviceUnit.WORD), 'LZ': DeviceCode(98, 10, DeviceUnit.WORD), 'R': DeviceCode(175, 10, DeviceUnit.WORD), 'ZR': DeviceCode(176, 10, DeviceUnit.WORD), 'RD': DeviceCode(44, 10, DeviceUnit.WORD), 'G': DeviceCode(171, 10, DeviceUnit.WORD), 'HG': DeviceCode(46, 10, DeviceUnit.WORD)}
module-attribute
SlmpDeviceModification = SlmpIndexZ | SlmpIndexLz | SlmpIndirect
module-attribute
__version__ = '5.0.0'
module-attribute
__all__ = ['AsyncSlmpClient', 'BlockReadResult', 'Command', 'CpuOperationState', 'CpuOperationStatus', 'DEVICE_CODES', 'DeviceBlockResult', 'DeviceRef', 'FrameType', 'LabelArrayReadPoint', 'LabelArrayReadResult', 'LabelArrayWritePoint', 'LabelRandomReadResult', 'LabelRandomWritePoint', 'LongTimerResult', 'ModuleIONo', 'MonitorResult', 'PLCSeries', 'RemoteClearMode', 'SlmpConnectionOptions', 'SlmpAddress', 'RandomReadResult', 'SlmpClient', 'SlmpBoundaryBehaviorWarning', 'SlmpClosedError', 'SlmpError', 'SlmpErrorInfo', 'SlmpNotConnectedError', 'SlmpOutcomeUnknownError', 'SlmpOutcomeUnknownReason', 'SlmpPlcProfile', 'SlmpPlcProfileDescriptor', 'available_plc_profiles', 'SlmpProfileFeatureError', 'SlmpPracticalPathWarning', 'SlmpTimeoutError', 'SlmpTransportError', 'SlmpUnsupportedDeviceError', 'SlmpResponse', 'SlmpTarget', 'SlmpTrafficStats', 'TypeNameInfo', 'decode_cpu_operation_state', 'display_name', 'format_address', 'get_end_code_name', 'is_remote_password_end_code', 'SlmpDeviceRangeCatalog', 'SlmpDeviceRangeCategory', 'SlmpDeviceRangeEntry', 'SlmpDeviceRangeNotation', 'SlmpDeviceModification', 'SlmpExtendedDevice', 'SlmpIndexLz', 'SlmpIndexZ', 'SlmpIndirect', 'normalize_address', 'normalize_plc_profile', 'open_and_connect', 'open_and_connect_sync', 'parse_address', 'plc_profile_descriptors', 'parse_device', 'poll', 'poll_sync', 'read_bits', 'read_bits_sync', 'read_dwords', 'read_dwords_single_request', 'read_dwords_single_request_sync', 'read_dwords_sync', 'read_named', 'read_named_sync', 'read_typed', 'read_typed_sync', 'read_device_range_catalog_for_plc_profile', 'read_device_range_catalog_for_plc_profile_sync', 'read_words', 'read_words_single_request', 'read_words_single_request_sync', 'read_words_sync', 'write_bit_in_word', 'write_bit_in_word_sync', 'write_bits', 'write_bits_sync', 'write_dwords_single_request', 'write_dwords_single_request_sync', 'write_named', 'write_named_sync', 'write_typed', 'write_typed_sync', 'write_words_single_request', 'write_words_single_request_sync', 'try_parse_address', 'build_device_range_catalog_for_plc_profile', 'plc_profile_canonical_name', 'device_range_model_label']
module-attribute
AsyncSlmpClient
Asynchronous SLMP client supporting 3E and 4E frames (binary) over TCP and UDP.
traffic_stats()
Return a read-only snapshot of cumulative traffic for this client lifetime.
connect()
async
Open the connection to the PLC.
close()
async
Close transport and reject the active and queued operation generation.
raw_command(command, *, subcommand, payload, target=None, monitoring_timer=None, raise_on_error=None, state_changing=None)
async
Send one maintainer-level raw SLMP command.
The frame serial is always allocated by the client so response
correlation cannot be bypassed by public callers. Unknown raw commands
are state-changing by default. Pass state_changing=False only for a
known or vendor-specific read-only command; known state-changing
commands cannot be downgraded.
read_devices(device, points, *, bit_unit)
async
Read device values from the PLC.
write_devices(device, values, *, bit_unit)
async
Write device values to the PLC.
read_dword(device)
async
Read one 32-bit value from two consecutive word devices.
write_dword(device, value)
async
Write one 32-bit value to two consecutive word devices.
read_dwords(device, count)
async
Read one or more 32-bit values from two consecutive word devices.
write_dwords(device, values)
async
Write one or more 32-bit values to two consecutive word devices.
read_float32(device)
async
Read one IEEE-754 float32 from two consecutive word devices.
write_float32(device, value)
async
Write one IEEE-754 float32 to two consecutive word devices.
read_float32s(device, count)
async
Read one or more IEEE-754 float32 values from two consecutive word devices.
write_float32s(device, values)
async
Write one or more IEEE-754 float32 values to two consecutive word devices.
read_devices_ext(device, points, *, bit_unit)
async
Read device values using Extended Device extension.
write_devices_ext(device, values, *, bit_unit)
async
Write device values using Extended Device extension.
read_random(*, word_devices=(), dword_devices=())
async
Read multiple word and double-word devices in a single request.
read_random_ext(*, word_devices=(), dword_devices=())
async
Read multiple word and double-word devices using Extended Device extension.
write_random_words(*, word_values=(), dword_values=())
async
Write multiple word and double-word devices in a single request.
write_random_words_ext(*, word_values=(), dword_values=())
async
Write multiple word and double-word devices using Extended Device extension.
write_random_bits(bit_values)
async
Write multiple bit devices in a single request.
write_random_bits_ext(bit_values)
async
Write multiple bit devices using Extended Device extension.
register_monitor_devices(*, word_devices=(), dword_devices=())
async
Register devices for monitoring.
register_monitor_devices_ext(*, word_devices=(), dword_devices=())
async
Register devices for monitoring using Extended Device extension.
run_monitor_cycle(*, word_points, dword_points)
async
Execute one cycle with a nonzero count within the profile monitor limit.
read_block(*, word_blocks=(), bit_blocks=())
async
Read multiple blocks of devices.
write_block(*, word_blocks=(), bit_blocks=())
async
Write multiple blocks of devices.
read_type_name()
async
Read the PLC type name and model code.
read_device_range_catalog_for_plc_profile(plc_profile)
async
Read the configured device-range catalog for one canonical explicit PLC profile.
read_device_range_catalog()
async
Read the configured device-range catalog for this client's explicit PLC profile.
read_cpu_operation_state()
async
Read SD203 and decode the CPU operation state from the lower 4 bits.
remote_run(*, force, clear_mode)
async
Remote run the PLC.
remote_stop()
async
Remote stop the PLC.
remote_pause(*, force)
async
Remote pause the PLC.
remote_latch_clear()
async
Remote latch clear the PLC.
clear_error()
async
Clear the current PLC error using the fixed semantic command.
remote_reset()
async
Remote reset the PLC without waiting for a response.
remote_password_lock(password)
async
Remote password lock the PLC.
remote_password_unlock(password)
async
Remote password unlock the PLC.
self_test_loopback(data)
async
Execute a self-test loopback.
read_array_labels(points, *, abbreviation_labels=())
async
Read array labels from the PLC.
write_array_labels(points, *, abbreviation_labels=())
async
Write array labels to the PLC.
read_random_labels(labels, *, abbreviation_labels=())
async
Read random labels from the PLC.
write_random_labels(points, *, abbreviation_labels=())
async
Write random labels to the PLC.
memory_read_words(head_address, word_length)
async
Read memory words from the PLC.
memory_write_words(head_address, values)
async
Write memory words to the PLC.
extend_unit_read_words(head_address, word_length, module_no)
async
Read words from an extend unit.
extend_unit_write_words(head_address, module_no, values)
async
Write words to an extend unit.
read_long_timer(*, head_no, points)
async
Read long timers from the PLC.
read_long_retentive_timer(*, head_no, points)
async
Read long retentive timers from the PLC.
read_ltc_states(*, head_no, points)
async
Read long timer coil states.
read_lts_states(*, head_no, points)
async
Read long timer contact states.
read_lstc_states(*, head_no, points)
async
Read long retentive timer coil states.
read_lsts_states(*, head_no, points)
async
Read long retentive timer contact states.
extend_unit_read_bytes(head_address, byte_length, module_no)
async
Read bytes from an extend unit.
extend_unit_read_word(head_address, module_no)
async
Read a single word from an extend unit.
extend_unit_read_dword(head_address, module_no)
async
Read a double word from an extend unit.
extend_unit_write_bytes(head_address, module_no, data)
async
Write bytes to an extend unit.
extend_unit_write_word(head_address, module_no, value)
async
Write a single word to an extend unit.
extend_unit_write_dword(head_address, module_no, value)
async
Write a double word to an extend unit.
BlockReadResult
dataclass
Result of block device read.
Command
Bases: IntEnum
Command list from SH080956ENGN 5.1.
CpuOperationState
dataclass
Decoded CPU operation state read from SD203.
CpuOperationStatus
Bases: str, Enum
Decoded CPU operation state from the lower 4 bits of SD203.
DeviceBlockResult
dataclass
Result of a single device block in block access.
DeviceRef
dataclass
Immutable profile-bound semantic device reference.
Attributes:
| Name | Type | Description |
|---|---|---|
code |
str
|
Device code string (e.g. 'D', 'X'). |
number |
int
|
Wire-level device address number. |
plc_profile |
str | SlmpPlcProfile
|
Canonical PLC profile used to interpret and format the address. |
FrameType
Bases: str, Enum
SLMP frame type (3E or 4E).
LabelArrayReadPoint
dataclass
Request point for array label read.
LabelArrayReadResult
dataclass
Result of array label read.
LabelArrayWritePoint
dataclass
Request point for array label write.
LabelRandomReadResult
dataclass
Result of random label read.
LabelRandomWritePoint
dataclass
Request point for random label write.
LongTimerResult
dataclass
Result of long timer read.
ModuleIONo
Bases: IntEnum
Request destination module I/O No. from SLMP specification SH080956ENGN 4.2.
MonitorResult
dataclass
Result of registered monitor device read.
PLCSeries
Bases: str, Enum
Series option for subcommand compatibility.
RemoteClearMode
Bases: IntEnum
Explicit device-clear policy for remote RUN.
SlmpConnectionOptions
dataclass
Stable connection settings for one SLMP session.
The options object is the recommended input for :func:open_and_connect
and :func:open_and_connect_sync. It keeps transport-level settings and
protocol-level defaults together so maintained documentation can point users to
one explicit connection entry point.
Attributes:
| Name | Type | Description |
|---|---|---|
host |
str
|
PLC hostname or IP address. |
plc_profile |
object
|
Canonical high-level PLC profile. This is the only application-level PLC selector for the recommended helper layer. |
port |
int
|
Required TCP or UDP port used by the SLMP endpoint. |
transport |
str
|
Transport name such as |
timeout |
float
|
One absolute deadline for each admitted operation, covering explicit connection establishment or lazy connection through the complete request exchange, in seconds. |
default_target |
SlmpTarget
|
Optional routing target applied to requests. |
monitoring_timer |
int
|
SLMP monitoring timer encoded into frames. |
raise_on_error |
bool
|
Whether protocol errors raise exceptions immediately. |
plc_series |
PLCSeries
|
Derived access profile fixed by |
frame_type |
FrameType
|
Derived frame type fixed by |
address_profile |
str
|
Derived address profile used for string device parsing. |
range_profile |
str
|
Derived range profile used for device-range catalog reads. |
SlmpAddress
dataclass
Parsed public SLMP helper-layer address notation.
RandomReadResult
dataclass
Result of random device read.
SlmpClient
Synchronous SLMP client supporting 3E and 4E frames (binary).
This client provides high-level typed APIs for interacting with MELSEC and compatible PLCs using the SLMP protocol.
Examples:
>>> from slmp.client import SlmpClient
>>> with SlmpClient("192.168.250.100", 1025, plc_profile="melsec:iq-r") as client:
... values = client.read_devices("D100", 5, bit_unit=False)
... print(values)
[0, 0, 0, 0, 0]
traffic_stats()
Return a read-only snapshot of cumulative traffic for this client lifetime.
connect()
Open the connection to the PLC.
Raises:
| Type | Description |
|---|---|
error
|
If the connection fails. |
close()
Close transport and reject the active and queued operation generation.
raw_command(command, *, subcommand, payload, target=None, monitoring_timer=None, raise_on_error=None, state_changing=None)
Send one maintainer-level raw SLMP command.
The frame serial is always allocated by the client so response
correlation cannot be bypassed by public callers. Unknown raw commands
are state-changing by default. Pass state_changing=False only for a
known or vendor-specific read-only command; known state-changing
commands cannot be downgraded.
read_devices(device, points, *, bit_unit)
Read device values from the PLC.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
device
|
str | DeviceRef
|
Device reference string (e.g. 'D100', 'X0') or |
required |
points
|
int
|
Number of consecutive points to read. |
required |
bit_unit
|
bool
|
If True, read in bit units (returns list of bool); otherwise read in word units (returns list of int). |
required |
Returns:
| Type | Description |
|---|---|
list[int] | list[bool]
|
A list of integers (for word units) or booleans (for bit units). |
Raises:
| Type | Description |
|---|---|
SlmpError
|
If the PLC returns an error code. |
ValueError
|
If |
write_devices(device, values, *, bit_unit)
Write values to PLC devices.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
device
|
str | DeviceRef
|
Starting device reference (e.g. 'D100', 'Y0') or |
required |
values
|
Sequence[int | bool]
|
Sequence of values to write. |
required |
bit_unit
|
bool
|
If True, write in bit units (expects Sequence[bool]); otherwise write in word units (expects Sequence[int]). |
required |
Raises:
| Type | Description |
|---|---|
SlmpError
|
If the PLC returns an error code. |
ValueError
|
If |
read_dword(device)
Read one 32-bit value from two consecutive word devices.
write_dword(device, value)
Write one 32-bit value to two consecutive word devices.
read_dwords(device, count)
Read one or more 32-bit values from consecutive word devices.
write_dwords(device, values)
Write one or more 32-bit values to two consecutive word devices.
read_float32(device)
Read one IEEE-754 float32 from two consecutive word devices.
write_float32(device, value)
Write one IEEE-754 float32 to two consecutive word devices.
read_float32s(device, count)
Read one or more IEEE-754 float32 values from consecutive word devices.
write_float32s(device, values)
Write one or more IEEE-754 float32 values to two consecutive word devices.
read_devices_ext(device, points, *, bit_unit)
Read a qualified Extended Device address with fields derived from the address.
write_devices_ext(device, values, *, bit_unit)
Write a qualified Extended Device address with fields derived from the address.
read_random(*, word_devices=(), dword_devices=())
read_random_ext(*, word_devices=(), dword_devices=())
Read multiple word and double-word devices at random using Extended Device extensions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
word_devices
|
Sequence[str | SlmpExtendedDevice]
|
Qualified word-device addresses. |
()
|
dword_devices
|
Sequence[str | SlmpExtendedDevice]
|
Qualified double-word-device addresses. |
()
|
write_random_words(*, word_values=(), dword_values=())
Write multiple word and double-word values at random.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
word_values
|
Mapping[str | DeviceRef, int] | Sequence[tuple[str | DeviceRef, int]]
|
Mapping or sequence of (device, value) for word devices. |
()
|
dword_values
|
Mapping[str | DeviceRef, int] | Sequence[tuple[str | DeviceRef, int]]
|
Mapping or sequence of (device, value) for double-word devices. |
()
|
write_random_words_ext(*, word_values=(), dword_values=())
Write multiple word and double-word values at random using Extended Device extensions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
word_values
|
Sequence[tuple[str | SlmpExtendedDevice, int]]
|
Qualified (device, value) pairs for word devices. |
()
|
dword_values
|
Sequence[tuple[str | SlmpExtendedDevice, int]]
|
Qualified (device, value) pairs for double-word devices. |
()
|
write_random_bits(bit_values)
write_random_bits_ext(bit_values)
Write multiple bit values at random using Extended Device extensions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bit_values
|
Sequence[tuple[str | SlmpExtendedDevice, bool]]
|
Qualified (device, value) pairs for bit devices. |
required |
register_monitor_devices(*, word_devices=(), dword_devices=())
register_monitor_devices_ext(*, word_devices=(), dword_devices=())
Register devices for monitoring using Extended Device extensions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
word_devices
|
Sequence[str | SlmpExtendedDevice]
|
Qualified word-device addresses. |
()
|
dword_devices
|
Sequence[str | SlmpExtendedDevice]
|
Qualified double-word-device addresses. |
()
|
run_monitor_cycle(*, word_points, dword_points)
Execute a monitoring cycle for previously registered devices.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
word_points
|
int
|
Number of registered word points. Combined count must be within the active profile's monitor-registration limit. |
required |
dword_points
|
int
|
Number of registered double-word points. Both counts cannot be zero. |
required |
Returns:
| Type | Description |
|---|---|
MonitorResult
|
MonitorResult containing the read values. |
read_block(*, word_blocks=(), bit_blocks=())
Read word blocks and bit-device word blocks.
write_block(*, word_blocks=(), bit_blocks=())
Write word blocks and bit-device word blocks.
read_long_timer(*, head_no, points)
Read long timer (LT) by LTN in 4-word units and decode status bits.
read_long_retentive_timer(*, head_no, points)
Read long retentive timer (LST) by LSTN in 4-word units and decode status bits.
read_ltc_states(*, head_no, points)
Read LT coil states by decoding LTN 4-word units.
read_lts_states(*, head_no, points)
Read LT contact states by decoding LTN 4-word units.
read_lstc_states(*, head_no, points)
Read LST coil states by decoding LSTN 4-word units.
read_lsts_states(*, head_no, points)
Read LST contact states by decoding LSTN 4-word units.
memory_read_words(head_address, word_length)
Read 16-bit words from intelligent function module/special function module buffer memory.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
head_address
|
int
|
Start address. |
required |
word_length
|
int
|
Number of words to read. |
required |
Returns:
| Type | Description |
|---|---|
list[int]
|
List of 16-bit word values. |
memory_write_words(head_address, values)
Write 16-bit words to intelligent function module/special function module buffer memory.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
head_address
|
int
|
Start address. |
required |
values
|
Sequence[int]
|
Sequence of 16-bit word values to write. |
required |
extend_unit_read_bytes(head_address, byte_length, module_no)
Read bytes from multiple-CPU shared memory or other extended units.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
head_address
|
int
|
Start address. |
required |
byte_length
|
int
|
Number of bytes to read. |
required |
module_no
|
int
|
Module number or unit identification. |
required |
Returns:
| Type | Description |
|---|---|
bytes
|
Read data as bytes. |
extend_unit_read_words(head_address, word_length, module_no)
Read 16-bit words from multiple-CPU shared memory or other extended units.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
head_address
|
int
|
Start address. |
required |
word_length
|
int
|
Number of words to read. |
required |
module_no
|
int
|
Module number or unit identification. |
required |
Returns:
| Type | Description |
|---|---|
list[int]
|
List of 16-bit word values. |
extend_unit_read_word(head_address, module_no)
Read one 16-bit word from an extend-unit buffer.
extend_unit_read_dword(head_address, module_no)
Read one 32-bit value from an extend-unit buffer.
extend_unit_write_bytes(head_address, module_no, data)
Write bytes to multiple-CPU shared memory or other extended units.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
head_address
|
int
|
Start address. |
required |
module_no
|
int
|
Module number or unit identification. |
required |
data
|
bytes
|
Bytes to write. |
required |
extend_unit_write_words(head_address, module_no, values)
Write 16-bit words to multiple-CPU shared memory or other extended units.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
head_address
|
int
|
Start address. |
required |
module_no
|
int
|
Module number or unit identification. |
required |
values
|
Sequence[int]
|
Sequence of 16-bit word values to write. |
required |
extend_unit_write_word(head_address, module_no, value)
Write one 16-bit word to an extend-unit buffer.
extend_unit_write_dword(head_address, module_no, value)
Write one 32-bit value to an extend-unit buffer.
remote_run(*, force, clear_mode)
Remote RUN.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
force
|
bool
|
Force RUN even if the RUN/STOP switch is at STOP. |
required |
clear_mode
|
RemoteClearMode
|
Clear mode (0: No clear, 1: Clear except latch, 2: Clear all). |
required |
remote_stop()
Remote STOP.
remote_pause(*, force)
Remote PAUSE.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
force
|
bool
|
Force PAUSE. |
required |
remote_latch_clear()
Remote latch clear.
clear_error()
Clear the current PLC error using the fixed semantic command.
remote_reset()
Remote RESET without waiting for a response, as required by the protocol contract.
remote_password_lock(password)
Remote password lock.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
password
|
str
|
Password string. |
required |
remote_password_unlock(password)
Remote password unlock.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
password
|
str
|
Password string. |
required |
self_test_loopback(data)
Self-test (loopback).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
bytes | str
|
Data to send for loopback test. |
required |
Returns:
| Type | Description |
|---|---|
bytes
|
Received loopback data. |
read_array_labels(points, *, abbreviation_labels=())
Read multiple array labels.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
points
|
Sequence[LabelArrayReadPoint]
|
List of array labels and points to read. |
required |
abbreviation_labels
|
Sequence[str]
|
Optional list of abbreviation labels. |
()
|
Returns:
| Type | Description |
|---|---|
list[LabelArrayReadResult]
|
List of LabelArrayReadResult. |
write_array_labels(points, *, abbreviation_labels=())
Write multiple array labels.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
points
|
Sequence[LabelArrayWritePoint]
|
List of array labels and data to write. |
required |
abbreviation_labels
|
Sequence[str]
|
Optional list of abbreviation labels. |
()
|
read_random_labels(labels, *, abbreviation_labels=())
Read multiple labels at random.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
labels
|
Sequence[str]
|
List of label names to read. |
required |
abbreviation_labels
|
Sequence[str]
|
Optional list of abbreviation labels. |
()
|
Returns:
| Type | Description |
|---|---|
list[LabelRandomReadResult]
|
List of LabelRandomReadResult. |
write_random_labels(points, *, abbreviation_labels=())
Write multiple labels at random.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
points
|
Sequence[LabelRandomWritePoint]
|
List of labels and data to write. |
required |
abbreviation_labels
|
Sequence[str]
|
Optional list of abbreviation labels. |
()
|
read_type_name()
Read the PLC model name and code.
read_device_range_catalog_for_plc_profile(plc_profile)
Read the configured device-range catalog for one canonical explicit PLC profile.
read_device_range_catalog()
Read the configured device-range catalog for this client's explicit PLC profile.
read_cpu_operation_state()
Read SD203 and decode the CPU operation state from the lower 4 bits.
SlmpBoundaryBehaviorWarning
Bases: UserWarning
Warning for target-specific boundary behavior that may differ from simple range assumptions.
SlmpClosedError
SlmpError
Bases: Exception
SLMP protocol error or error response.
end_code_name
property
Return a compact symbolic name for the SLMP end code, if present.
is_remote_password_error
property
Return True when this error is related to remote password protection.
SlmpErrorInfo
dataclass
Structured SLMP error information returned after a non-zero end code.
parse(data)
classmethod
Parse the 9-byte SLMP error information block, if present.
SlmpNotConnectedError
SlmpOutcomeUnknownError
SlmpOutcomeUnknownReason
Bases: str, Enum
Machine-readable reasons why a state-changing outcome is unknown.
SlmpPlcProfile
Bases: str, Enum
Canonical PLC profile used by high-level SLMP helpers.
SlmpPlcProfileDescriptor
dataclass
One canonical PLC profile and its connection-selection metadata.
SlmpProfileFeatureError
Bases: ValueError
Raised before transport when strict profile checks block a high-level feature.
SlmpPracticalPathWarning
Bases: UserWarning
Warning for paths that are implemented but known to be problematic on validated targets.
SlmpTimeoutError
SlmpTransportError
Bases: SlmpError, ConnectionError
Raised for transport failures that are not local-close or timeout events.
SlmpUnsupportedDeviceError
Bases: ValueError
Project-level validation error for device families intentionally disabled in typed APIs.
SlmpResponse
dataclass
Decoded SLMP response frame.
Attributes:
| Name | Type | Description |
|---|---|---|
serial |
int
|
Serial number matching the request. |
target |
SlmpTarget
|
Source station routing information. |
end_code |
int
|
Response end code (0x0000 for success). |
data |
bytes
|
Command-specific response payload. |
raw |
bytes
|
Full raw binary response frame. |
error_info |
SlmpErrorInfo | None
|
Structured PLC error information when end_code is non-zero and present. |
is_success
property
Return True if the response end_code is 0.
SlmpTarget
dataclass
SLMP frame destination fields.
Attributes:
| Name | Type | Description |
|---|---|---|
network |
int
|
Network number (0x00 for local network). |
station |
int
|
Station number (0xFF for the connected station). |
module_io |
int | ModuleIONo | str
|
Module I/O number (0x03FF for own station). |
multidrop |
int
|
Multidrop station number (0x00 for no multidrop). |
SlmpTrafficStats
dataclass
Immutable lifetime traffic-counter snapshot for one client.
TypeNameInfo
dataclass
Result of READ_TYPE_NAME command.
SlmpDeviceRangeCatalog
dataclass
Resolved device-range catalog for one explicit PLC profile.
SlmpDeviceRangeCategory
Bases: str, Enum
Logical grouping for monitor-oriented range output.
SlmpDeviceRangeEntry
dataclass
One device entry in the resolved catalog.
SlmpDeviceRangeNotation
Bases: str, Enum
Public address notation for the rendered range string.
SlmpExtendedDevice
dataclass
Qualified Extended Device text plus an optional typed modification.
SlmpIndexLz
dataclass
Typed LZ long-index-register modification for one Extended Device operand.
SlmpIndexZ
dataclass
Typed Z index-register modification for one Extended Device operand.
SlmpIndirect
dataclass
Typed word-device indirect modification for one Extended Device operand.
available_plc_profiles()
Return profiles accepted by the standard connection helpers.
decode_cpu_operation_state(status_word)
Decode the CPU operation state from SD203 lower 4 bits.
display_name(plc_profile)
Return the canonical human-readable display name for a PLC profile.
format_address(address, *, plc_profile)
Return canonical public SLMP address text.
get_end_code_name(end_code)
Return the stable code-derived key for an SLMP end code.
is_remote_password_end_code(end_code)
Return True if the SLMP end code is related to remote password protection.
normalize_address(address, *, plc_profile)
Return the canonical helper-layer form of one SLMP device address.
The helper accepts free-form user text such as " d200:f " or an
already parsed :class:DeviceRef. The result is suitable for logs,
configuration files, and cache keys.
normalize_plc_profile(value)
Normalize one canonical PLC profile identifier.
open_and_connect(options)
async
Create and connect one async SLMP client.
This is the recommended async entry point for applications that share one connection across polling, named reads, and writes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
options
|
SlmpConnectionOptions
|
Stable connection settings for the session. |
required |
Returns:
| Type | Description |
|---|---|
AsyncSlmpClient
|
A connected :class: |
AsyncSlmpClient
|
FIFO operation queue; no wrapper is required. |
open_and_connect_sync(options)
Create and connect one synchronous SLMP client.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
options
|
SlmpConnectionOptions
|
Stable connection settings for the session. |
required |
Returns:
| Type | Description |
|---|---|
SlmpClient
|
A connected synchronous :class: |
parse_address(address, *, plc_profile)
Parse public SLMP helper-layer address notation.
Supported forms match :func:read_named: "D100:U", "D200:F",
"D50.A", and direct bit devices such as "M100:BIT".
plc_profile_descriptors()
Return all canonical profiles with display, connection, and base metadata.
The abstract melsec:qcpu entry is included with connectable=False
so selectors can explain why it cannot be opened directly.
parse_device(value, *, plc_profile)
Parse a device string into a DeviceRef.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
str | DeviceRef
|
Device string (e.g. 'D100', 'X1F') or |
required |
plc_profile
|
object
|
Exact canonical PLC profile that defines the device grammar. |
required |
Returns:
| Type | Description |
|---|---|
DeviceRef
|
A |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the profile is missing or ambiguous, the device format is
invalid, the code is unsupported, or a bound |
poll(client, addresses, interval)
async
Continuously yield mixed read results at a fixed interval.
The address list is compiled once and reused for every cycle.
poll_sync(client, addresses, interval)
Synchronously yield mixed read results at a fixed interval.
read_bits(client, device, count)
async
Read a contiguous bit-device range as booleans.
read_bits_sync(client, device, count)
Synchronously read a contiguous bit-device range as booleans.
read_dwords(client, device, count)
async
Read a contiguous DWord range using exactly one request.
read_dwords_single_request(client, device, count)
async
Read contiguous unsigned 32-bit values using one protocol request.
Adjacent word pairs are combined in little-endian order and never split across requests by this helper.
read_dwords_single_request_sync(client, device, count)
Synchronously read contiguous unsigned 32-bit values using one protocol request.
read_dwords_sync(client, device, count)
Synchronously read a contiguous DWord range using one request.
read_named(client, addresses)
async
Read a mixed logical collection by address string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client
|
AsyncSlmpClient
|
Connected async SLMP client. |
required |
addresses
|
list[str]
|
Address list such as |
required |
Returns:
| Type | Description |
|---|---|
dict[str, int | float | bool]
|
A dictionary keyed by the original address strings. |
Notes
The address list is compiled once, then grouped into random reads where
possible. Use .bit notation only with word devices.
read_named_sync(client, addresses)
Synchronously read a mixed logical collection by address string.
read_typed(client, device, dtype)
async
Read one logical value and convert it to a Python scalar.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client
|
AsyncSlmpClient
|
Connected high-level or raw async SLMP client. |
required |
device
|
str | DeviceRef
|
Starting device address as a string such as |
required |
dtype
|
str
|
Application type code. Supported values are |
required |
Returns:
| Type | Description |
|---|---|
int | float | bool
|
|
read_typed_sync(client, device, dtype)
Synchronously read one logical value as a Python scalar.
read_device_range_catalog_for_plc_profile(client, plc_profile)
async
Async variant of the canonical explicit-profile device-range catalog read.
read_device_range_catalog_for_plc_profile_sync(client, plc_profile)
Read one canonical profile SD window in a single request and build a catalog.
read_words(client, device, count)
async
Read a contiguous word-device range using exactly one request.
read_words_single_request(client, device, count)
async
Read contiguous 16-bit values using one protocol request.
Counts above the profile's one-request limit must be split explicitly by the application together with its required consistency checks.
read_words_single_request_sync(client, device, count)
Synchronously read contiguous 16-bit values using one protocol request.
read_words_sync(client, device, count)
Synchronously read a contiguous word-device range using one request.
write_bit_in_word(client, device, bit_index, value)
async
Set or clear one bit inside one word device.
This helper is only for word devices such as D50. Qualified U module-
buffer and J link-direct word addresses use their immutable Extended Device
route for both requests. Direct bit devices
such as M1000 should be written with :func:write_typed using
"BIT". It holds one client FIFO turn across a word read followed by a
word write. That prevents same-client interleaving but is not atomic at the
PLC: another connection or PLC logic can change the word between requests.
A possibly-sent write uses the outcome-unknown error contract. The helper
never retries automatically. One absolute deadline starts after FIFO
admission and covers both requests, and a successful read is always followed
by the write even when the selected bit is unchanged.
write_bit_in_word_sync(client, device, bit_index, value)
Synchronously update one word bit while holding one client FIFO turn.
Direct and qualified Extended Device routes are supported. The selected route is immutable across the two non-atomic PLC requests. Another connection or PLC logic can race with them, possibly-sent writes use the outcome-unknown error contract, and the helper never retries automatically. One absolute deadline covers both requests after FIFO admission, and the write is always sent after a successful read.
write_bits(client, device, values)
async
Write a contiguous bit-device range from booleans.
write_bits_sync(client, device, values)
Synchronously write a contiguous bit-device range from booleans.
write_dwords_single_request(client, device, values)
async
Write contiguous unsigned 32-bit values using one protocol request.
Each Python int is encoded as two PLC words in little-endian order.
write_dwords_single_request_sync(client, device, values)
Synchronously write contiguous unsigned 32-bit values using one protocol request.
write_named(client, updates)
async
Write a mixed logical collection by address string.
D50.3 updates one bit inside one word. Direct bit devices such as
M1000 are normalized to "BIT" writes.
write_named_sync(client, updates)
Synchronously write a mixed logical collection by address string.
write_typed(client, device, dtype, value)
async
Write one logical value using the requested application type.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client
|
AsyncSlmpClient
|
Connected high-level or raw async SLMP client. |
required |
device
|
str | DeviceRef
|
Starting device address. |
required |
dtype
|
str
|
Type code accepted by :func: |
required |
value
|
int | float | bool
|
Application value to encode and write. |
required |
write_typed_sync(client, device, dtype, value)
Synchronously write one logical value using the requested type.
write_words_single_request(client, device, values)
async
Write contiguous 16-bit values using one protocol request.
Use this helper for logical ranges that should stay within one protocol write operation.
write_words_single_request_sync(client, device, values)
Synchronously write contiguous 16-bit values using one protocol request.
try_parse_address(address, *, plc_profile)
Return parsed address information, or None when parsing fails.
build_device_range_catalog_for_plc_profile(plc_profile, registers)
Build one catalog from already-read profile SD registers.
plc_profile_canonical_name(plc_profile)
Return the canonical PLC profile identifier.
device_range_model_label(plc_profile)
Return the short model label used in device-range catalog metadata.