TOYOPUC Computerlink Python API Reference

This page is generated during the docs-site build from the installed plc-comm-toyopuc 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.

Generated API Details

toyopuc

TOYOPUC communication package with high-level helpers as the recommended user surface.

The primary user-facing entry points are:

• ToyopucConnectionOptions / open_and_connect
• read_typed / write_typed
• read_words_single_request / read_dwords_single_request
• write_bit_in_word
• read_named / poll

Low-level clients and address helpers remain exported for advanced workflows, but the helpers above are the preferred surface for normal application code and generated user documentation.

__version__ = '4.0.0' module-attribute

__all__ = ['ToyopucClient', 'ToyopucTrafficStats', 'AsyncToyopucClient', 'AsyncToyopucDeviceClient', 'ToyopucDeviceClient', 'ResolvedDevice', 'ClockData', 'CpuStatusData', 'RelayLayer', 'ToyopucError', 'ToyopucOperationOutcomeUnknownError', 'ToyopucOutcomeUnknownReason', 'ToyopucCancelledError', 'ToyopucClosedError', 'ToyopucNotConnectedError', 'ToyopucPlcError', 'ToyopucProtocolError', 'ToyopucTimeoutError', 'ToyopucTransportError', 'ToyopucConnectionOptions', 'ToyopucAddress', 'format_device_address', 'normalize_address', 'open_and_connect', 'parse_device_address', 'poll', 'read_dwords', 'read_dwords_single_request', 'read_named', 'read_typed', 'read_words', 'read_words_single_request', 'write_bit_in_word', 'write_dwords_single_request', 'write_typed', 'write_words_single_request', 'try_parse_device_address', 'parse_address', 'parse_prefixed_address', 'encode_word_address', 'encode_byte_address', 'encode_bit_address', 'encode_program_word_address', 'encode_program_byte_address', 'encode_program_bit_address', 'encode_exno_bit_u32', 'encode_exno_byte_u32', 'split_u32_words', 'encode_ext_no_address', 'fr_block_ex_no', 'encode_fr_word_addr32', 'parse_relay_hops', 'normalize_relay_hops', 'format_relay_hop', 'resolve_device', 'ToyopucAddressRange', 'ToyopucAreaDescriptor', 'ToyopucDeviceCatalog', 'ToyopucDeviceMatrixRow', 'ToyopucPlcProfile', 'ToyopucPlcProfileDescriptor', 'ToyopucPlcProfiles', 'display_name', 'plc_profile_descriptors'] module-attribute

ToyopucClient

Low-level TOYOPUC computer-link client.

Use this class when you want explicit control over command families, numeric addresses, and transport settings. For string-address driven use, prefer ToyopucDeviceClient. TCP and UDP connections are IPv4-only.

last_tx property

Last raw frame transmitted by this client, if available.

last_rx property

Last raw frame received by this client, if available.

traffic_stats()

Return an immutable lifetime traffic-counter snapshot.

connect()

Open TCP or UDP within one absolute DNS-through-adoption deadline.

close()

Interrupt active work and retire all operations admitted before this call.

read_words(addr, count)

Read one or more basic-area words with CMD=1C.

write_words(addr, values)

Write one or more basic-area words with CMD=1D.

read_bytes(addr, count)

Read one or more basic-area bytes with CMD=1E.

write_bytes(addr, values)

Write one or more basic-area bytes with CMD=1F.

read_bit(addr)

Read one basic-area bit with CMD=20.

write_bit(addr, value)

Write one basic-area bit with CMD=21; value must be bool.

read_dword(addr)

Read one 32-bit value from two consecutive words.

write_dword(addr, value)

Write one 32-bit value to two consecutive words.

read_dwords(addr, count)

Read one or more 32-bit values from consecutive words.

write_dwords(addr, values)

Write one or more 32-bit values to consecutive words.

read_float32(addr)

Read one IEEE-754 float32 from two consecutive words.

write_float32(addr, value)

Write one IEEE-754 float32 to two consecutive words.

read_float32s(addr, count)

Read one or more IEEE-754 float32 values from consecutive words.

write_float32s(addr, values)

Write one or more IEEE-754 float32 values to consecutive words.

read_words_multi(addrs)

Read multiple non-contiguous basic-area words with CMD=22.

write_words_multi(pairs)

Write multiple non-contiguous basic-area words with CMD=23.

read_bytes_multi(addrs)

Read multiple non-contiguous basic-area bytes with CMD=24.

write_bytes_multi(pairs)

Write multiple non-contiguous basic-area bytes with CMD=25.

read_ext_words(no, addr, count)

Read extended-area words with CMD=94 using (No., addr).

write_ext_words(no, addr, values)

Write extended-area words with CMD=95 using (No., addr).

read_ext_bytes(no, addr, count)

Read extended-area bytes with CMD=96 using (No., addr).

write_ext_bytes(no, addr, values)

Write extended-area bytes with CMD=97 using (No., addr).

read_ext_multi(bit_points, byte_points, word_points)

Read mixed extended points with CMD=98.

bit_points items are (no, bit_no, addr). byte_points items are (no, addr). word_points items are (no, addr).

All addr fields are monitor byte addresses, including word_points (manual: "byte address N"). A CMD=94 word address must be doubled before it is used as a word_points address.

write_ext_multi(bit_points, byte_points, word_points)

Write mixed extended points with CMD=99.

All addr fields are monitor byte addresses, including word_points (manual: "byte address N"), as in :meth:read_ext_multi. Each bit point value must be an actual bool.

pc10_block_read(addr32, count)

Read PC10 block data with CMD=C2 from a 32-bit byte address.

pc10_block_write(addr32, data_bytes)

Write PC10 block data with CMD=C3 to a 32-bit byte address.

pc10_multi_read(payload)

Read PC10 multi-point data with CMD=C4 using a prebuilt payload.

pc10_multi_write(payload)

Write PC10 multi-point data with CMD=C5 using a prebuilt payload.

read_fr_words(index, count)

Read FR words via exactly one PC10 block-read request (CMD=C2).

FR real-hardware access uses 32-bit PC10 addressing with Ex No.=0x40-0x7F, not CMD=94.

write_fr_words(index, values)

Update the FR work area with exactly one PC10 block-write request.

This method never commits flash. Call :meth:commit_fr_block separately with an explicit block-start index when persistence is intended.

commit_fr_block(block_start_index)

Commit exactly one explicitly selected FR block with CMD=CA.

relay_command(link_no, station_no, inner_payload)

Wrap a command in one relay hop using CMD=60.

relay_nested(hops, inner_payload)

Wrap a command in multiple relay hops using nested CMD=60 frames.

send_via_relay(hops, inner_payload)

Send a command through relay hops and return the final inner response.

relay_read_words(hops, addr, count)

Read one or more basic-area words through relay hops.

relay_write_words(hops, addr, values)

Write one or more basic-area words through relay hops.

relay_read_clock(hops)

Read the CPU clock through relay hops.

relay_write_clock(hops, value, *, year_base)

Set the CPU clock through relay hops via CMD=32 / 71 00.

relay_resume_scan(hops)

Resume CPU scan through relay hops via CMD=32 / 01 00.

relay_stop_scan(hops)

Stop CPU scan through relay hops via CMD=32 / 02 00 01.

relay_release_scan_stop(hops)

Release CPU scan stop through relay hops via CMD=32 / 02 00 00.

relay_read_cpu_status(hops)

Read the 8-byte CPU status block through relay hops.

relay_read_cpu_status_a0_raw(hops)

Read raw 8-byte CPU status through relay hops via CMD=A0 / 00 11 00.

relay_read_cpu_status_a0(hops)

Read decoded CPU status through relay hops via CMD=A0 / 00 11 00.

relay_write_fr_words(hops, index, values)

Update the remote FR work area with exactly one request.

relay_commit_fr_block(hops, block_start_index)

Commit exactly one explicitly selected remote FR block.

read_clock()

Read the CPU clock via CMD=32 / 70 00.

read_cpu_status()

Read the 8-byte CPU status block via CMD=32 / 11 00.

read_cpu_status_a0_raw()

Read raw 8-byte CPU status via CMD=A0 / 00 11 00.

This command path is used in the flash/FR completion flow. The library currently returns the 8 raw status bytes because the exact bit mapping for this path has not been finalized yet.

read_cpu_status_a0()

Read decoded CPU status via CMD=A0 / 00 11 00.

write_clock(value, *, year_base)

Set the CPU clock via CMD=32 / 71 00.

resume_scan()

Resume CPU scan via CMD=32 / 01 00.

stop_scan()

Stop CPU scan via CMD=32 / 02 00 01.

release_scan_stop()

Release CPU scan stop via CMD=32 / 02 00 00.

ToyopucTrafficStats dataclass

Immutable lifetime traffic counters for one client.

AsyncToyopucClient

Bases: _AsyncToyopucClientBase

Native-async low-level TOYOPUC client.

AsyncToyopucDeviceClient

Bases: _AsyncToyopucClientBase

Native-async high-level TOYOPUC client.

read(device, count) async

Read a contiguous high-level device range with native async transport.

read_devices(devices) async

Read sparse high-level devices in caller order with native async transport.

relay_read(hops, device, count) async

Read a contiguous high-level device range through explicit relay hops.

relay_read_devices(hops, devices) async

Read sparse high-level devices through explicit relay hops in caller order.

ToyopucDeviceClient

Bases: ToyopucClient

High-level client that accepts string device addresses.

resolve_device(device)

Resolve a string address into a ResolvedDevice.

relay_read_one(hops, device)

Read exactly one item through relay hops and return a scalar.

relay_read(hops, device, count)

Read a contiguous sequence through relay hops, splitting only when required.

relay_write(hops, device, value)

Write one item or a contiguous sequence through relay hops.

relay_read_words(hops, device, count)

Read one or more word devices through relay hops.

relay_write_words(hops, device, value)

Write one or more word devices through relay hops.

relay_read_devices(hops, devices)

Read multiple devices through relay hops in caller order as one FIFO operation.

relay_write_many(hops, items)

Write multiple devices through relay hops as one compatible protocol request.

read_fr_one(device)

Read exactly one FR word and return a scalar.

read_fr(device, count)

Read contiguous FR words using exactly one PC10 block request.

relay_read_fr_one(hops, device)

Read exactly one FR word through relay hops and return a scalar.

relay_read_fr(hops, device, count)

Read contiguous FR words through relay hops using one request.

write_fr(device, value)

Update FR work-area words with exactly one request; never commit.

relay_write_fr(hops, device, value)

Update remote FR work-area words with one request; never commit.

commit_fr(device)

Commit the one FR block whose first word is explicitly specified.

relay_commit_fr(hops, device)

Commit one explicitly selected remote FR block.

read_one(device)

Read exactly one item and return a scalar.

read(device, count)

Read a contiguous sequence, splitting only when protocol capacity requires it.

write(device, value)

Write one item or a contiguous sequence to a device address.

write_bit_in_word(device, bit_index, value)

Set or clear one bit through an explicit 16-bit read-modify-write.

One local FIFO turn and one transaction deadline cover the read and write. The operation is not PLC-atomic: PLC logic or another connection can change the word between requests and that update can be lost. Use PLC-side coordination when the complete word is shared.

relay_write_bit_in_word(hops, device, bit_index, value)

Relay-route form of :meth:write_bit_in_word with the same risk contract.

read_devices(devices)

Read multiple devices in caller order as one non-atomic FIFO operation.

write_many(items)

Write multiple devices as one compatible protocol request in mapping iteration order.

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 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 consecutive word devices.

relay_read_dword(hops, device)

Read one 32-bit value through relay hops.

relay_write_dword(hops, device, value)

Write one 32-bit value through relay hops.

relay_read_dwords(hops, device, count)

Read one or more 32-bit values through relay hops.

relay_write_dwords(hops, device, values)

Write one or more 32-bit values through relay hops.

relay_read_float32(hops, device)

Read one IEEE-754 float32 through relay hops.

relay_write_float32(hops, device, value)

Write one IEEE-754 float32 through relay hops.

relay_read_float32s(hops, device, count)

Read one or more IEEE-754 float32 values through relay hops.

relay_write_float32s(hops, device, values)

Write one or more IEEE-754 float32 values through relay hops.

ResolvedDevice dataclass

Resolved high-level device description.

ClockData dataclass

Raw PLC clock fields returned by CMD=32 / 70 00.

Attributes:

Name	Type	Description
second	int	BCD-decoded seconds field.
minute	int	BCD-decoded minutes field.
hour	int	BCD-decoded hour field in 24-hour format.
day	int	BCD-decoded day-of-month field.
month	int	BCD-decoded month field. Some models can report 0 when the calendar part is unset.
year_2digit	int	Lower two digits of the year.
weekday	int	PLC weekday value where 0 means Sunday.

as_datetime(*, year_base)

Convert the PLC clock fields into a Python datetime.

CpuStatusData dataclass

Decoded container for the 8 CPU-status bytes from CMD=32 / 11 00.

The data1-data8 fields store the raw status bytes. The boolean properties expose the manual-defined flag meanings such as run, alarm, and program1_running.

raw_bytes property

Return the eight raw CPU-status bytes.

raw_bytes_hex property

Return the raw CPU-status bytes as space-separated hexadecimal text.

run property

Whether the PLC reports RUN state.

under_stop property

Whether the PLC reports STOP state.

under_stop_request_continuity property

Whether stop-request continuity is active.

under_pseudo_stop property

Whether pseudo-stop state is active.

debug_mode property

Whether debug mode is active.

io_monitor_user_mode property

Whether I/O monitor user mode is active.

pc3_mode property

Whether the CPU reports PC3 mode.

pc10_mode property

Whether the CPU reports PC10 mode.

fatal_failure property

Whether a fatal failure flag is set.

faint_failure property

Whether a faint failure flag is set.

alarm property

Whether an alarm flag is set.

io_allocation_parameter_altered property

Whether the I/O allocation parameter altered flag is set.

with_memory_card property

Whether the CPU reports a memory card present.

memory_card_operation property

Whether a memory-card operation flag is set.

write_protected_program_info property

Whether program information write protection is active.

read_protected_system_memory property

Whether system memory read protection is active.

write_protected_system_memory property

Whether system memory write protection is active.

read_protected_system_io property

Whether system I/O read protection is active.

write_protected_system_io property

Whether system I/O write protection is active.

trace property

Whether trace is active.

scan_sampling_trace property

Whether scan-sampling trace is active.

periodic_sampling_trace property

Whether periodic-sampling trace is active.

enable_detected property

Whether enable detection is flagged.

trigger_detected property

Whether trigger detection is flagged.

one_scan_step property

Whether one-scan-step execution is active.

one_block_step property

Whether one-block-step execution is active.

one_instruction_step property

Whether one-instruction-step execution is active.

io_offline property

Whether I/O offline state is active.

remote_run_setting property

Whether remote RUN setting is active.

status_latch_setting property

Whether status latch setting is active.

write_priority_limited_program_info property

Whether write-priority limited program information is active.

abnormal_write_flash_register property

Whether abnormal flash-register write is flagged.

under_writing_flash_register property

Whether flash-register writing is in progress.

abnormal_write_equipment_info property

Whether abnormal equipment-information write is flagged.

abnormal_writing_equipment_info property

Whether equipment-information writing is abnormal.

abnormal_write_during_run property

Whether abnormal write-during-RUN is flagged.

under_writing_during_run property

Whether write-during-RUN is in progress.

program3_running property

Whether program 3 is running.

program2_running property

Whether program 2 is running.

program1_running property

Whether program 1 is running.

raw_hex()

Return the raw CPU-status bytes as space-separated hexadecimal text.

RelayLayer dataclass

One decoded relay wrapper layer from a CMD=60 response.

ToyopucError

Bases: Exception

Base error for TOYOPUC communication.

ToyopucOperationOutcomeUnknownError

Bases: ToyopucError

Raised when a state-changing request may have reached the PLC.

ToyopucOutcomeUnknownReason

Bases: str, Enum

Machine-readable reason for an unknown state-changing operation outcome.

ToyopucCancelledError

Bases: ToyopucError

Raised when an operation is cancelled before its outcome becomes uncertain.

ToyopucClosedError

Bases: ToyopucError

Raised when close retires the operation's transport generation.

ToyopucNotConnectedError

Bases: ToyopucError

Raised when an explicit reconnect is required before another command.

ToyopucPlcError

Bases: ToyopucError

Raised for a syntactically valid PLC NG response.

ToyopucProtocolError

Bases: ToyopucError

Raised when the response frame is invalid or unexpected.

ToyopucTimeoutError

Bases: ToyopucError

Raised when the configured connect or transaction deadline expires.

ToyopucTransportError

Bases: ToyopucError

Raised for transport failures distinct from timeout and protocol decoding.

ToyopucConnectionOptions dataclass

Stable connection settings for one TOYOPUC session.

Attributes:

Name	Type	Description
host	str	PLC IPv4 address or hostname that resolves to IPv4.
port	int	TOYOPUC computer-link port.
local_port	int	UDP source port. Leave zero for an ephemeral port.
transport	str	"tcp" or "udp".
timeout	float	Absolute connection and per-request timeout in seconds. Maximum 2147483.647.
retries	int	Number of retry attempts performed by the async client.
retry_delay	float	Delay between retry attempts, in seconds. Maximum 2147483.647.
plc_profile	str	Canonical PLC profile name such as "toyopuc:pc10g:pc10". Required when creating a high-level device client.

ToyopucAddress dataclass

Parsed public device address notation.

text is the canonical full notation. base_device is the resolved PLC device without value-format or bit-in-word suffix.

ToyopucAddressRange dataclass

An inclusive integer range [start, end].

contains(index)

Return whether index falls inside this inclusive range.

ToyopucAreaDescriptor dataclass

Per-area metadata for a PLC profile.

Attributes:

Name	Type	Description
area	str	Area name (e.g. "D", "EP", "FR").
direct_ranges	tuple[ToyopucAddressRange, ...]	Valid index ranges for direct (non-prefixed) access.
prefixed_ranges	tuple[ToyopucAddressRange, ...]	Valid index ranges for P1-/P2-/P3- prefixed access.
supports_packed_word	bool	True when bit-device packed-word (W/L/H suffix) access is allowed.
address_width	int	Number of hex digits in the normal address field.
suggested_start_step	int	Step between suggested start addresses for UI.
packed_direct_ranges_override	tuple[ToyopucAddressRange, ...] | None	If set, overrides the shifted direct ranges used for packed/derived access.
packed_prefixed_ranges_override	tuple[ToyopucAddressRange, ...] | None	Same, for prefixed access.

supports_direct property

Whether this area supports non-prefixed direct access.

supports_prefixed property

Whether this area supports P1/P2/P3-prefixed access.

packed_address_width property

Address width used by packed/derived word or byte access.

uses_derived_access(unit, packed=False)

True when unit/packed combination uses shifted (derived) ranges.

get_address_width(unit, packed=False)

Return the expected hexadecimal digit width for an address unit.

get_ranges(prefixed, packed=False)

Return the valid index ranges for the given access mode.

Parameters:

Name	Type	Description	Default
prefixed	bool	True for P1-/P2-/P3- prefixed access, False for direct.	required
packed	bool	True when using derived/packed (shifted) ranges.	False

Returns:

Type	Description
tuple[ToyopucAddressRange, ...]	Tuple of valid address ranges.

get_ranges_for_unit(prefixed, unit, packed=False)

Return ranges applying derived-access logic for the given unit.

ToyopucDeviceCatalog

Convenience API for profile area metadata used by UI/device lists.

get_area_descriptors(profile=None) classmethod

Return all area descriptors for the selected PLC profile.

get_areas(prefixed, profile=None) classmethod

Return area names available for direct or prefixed access.

get_area_descriptor(area, profile=None) classmethod

Return metadata for one area in the selected PLC profile.

get_supported_ranges(area, prefixed, profile=None, *, unit=None, packed=False) classmethod

Return supported index ranges for one area/access/unit selection.

format_address_range(family_code, address_range, width) staticmethod

Format one address range with a family code and fixed hexadecimal width.

format_address_ranges(family_code, ranges, width) staticmethod

Format multiple address ranges as comma-separated text.

get_device_matrix(profile=None) classmethod

Return a compact device/profile matrix for release review.

When profile is omitted, rows for all known profiles are returned. Prefixed rows use P1- as the representative program prefix.

get_supported_range(area, prefixed, profile=None, *, unit=None, packed=False) classmethod

Return the single supported range for an area or raise if there are several.

is_supported_index(area, index, prefixed, profile=None, *, unit=None, packed=False) classmethod

Return whether an index is supported for one area/access/unit selection.

get_suggested_start_addresses(area, prefix=None, profile=None, *, unit=None, packed=False, options=None) classmethod

Return representative start addresses that can be resolved for an area.

ToyopucDeviceMatrixRow dataclass

One review row in the maintained profile/device addressing matrix.

to_dict()

Return a JSON-serializable representation of this matrix row.

ToyopucPlcProfile dataclass

A named device model configuration with area descriptors and options.

ToyopucPlcProfileDescriptor dataclass

Metadata used to present and select one canonical TOYOPUC PLC profile.

ToyopucPlcProfiles

Catalog of all known TOYOPUC PLC profiles.

get_names() classmethod

Return canonical PLC profile names known to the catalog.

profile_descriptors() classmethod

Return presentation and connection metadata for every canonical PLC profile.

from_name(profile) classmethod

Resolve a canonical PLC profile name to its profile object.

display_name(profile) classmethod

Return the canonical human-readable display name for a PLC profile.

get_area_descriptor(area, profile=None) classmethod

Return metadata for one area in the selected PLC profile.

format_device_address(address, *, profile=None)

Return canonical public address text for a parsed address or string.

normalize_address(device, *, profile)

Return the canonical TOYOPUC device string.

Parameters:

Name	Type	Description	Default
device	str	User-facing device text such as "p1-d0100".	required
profile	str	Required canonical addressing profile used by :func:resolve_device.	required

Returns:

Type	Description
str	Canonical uppercase address text suitable for logs and configuration
str	storage.

open_and_connect(options) async

Create and connect an AsyncToyopucDeviceClient.

Parameters:

Name	Type	Description	Default
options	ToyopucConnectionOptions	Validated explicit connection options.	required

Returns:

Type	Description
AsyncToyopucDeviceClient	A connected AsyncToyopucDeviceClient.

parse_device_address(device, *, profile)

Parse user-facing TOYOPUC address notation.

Supported forms match :func:read_named:

• "P1-D0100:U" as unsigned 16-bit word notation
• "P1-D0100:F" with explicit dtype U/S/D/L/F
• "P1-D0100.A" for one bit inside a word

poll(client, addresses, interval) async

Yield one named-device read result every interval seconds.

This helper performs repeated :func:read_named calls and sleeps for the requested interval between read results.

Parameters:

Name	Type	Description	Default
client	AsyncToyopucDeviceClient	Connected AsyncToyopucDeviceClient.	required
addresses	list[str]	Non-empty list of unique named addresses.	required
interval	float	Poll interval in seconds. It must be greater than zero and no greater than 2147483.647.	required

Usage::

async for read_result in poll(client, ["P1-D0100:U"], interval=1.0):
    print(read_result)

read_dwords(client, device, count) async

Read count contiguous DWord (32-bit unsigned) values starting at device.

Reads count * 2 words and combines adjacent word pairs (lo, hi).

Parameters:

Name	Type	Description	Default
client	AsyncToyopucDeviceClient	Connected AsyncToyopucDeviceClient.	required
device	str	Starting device address string (must be a word device).	required
count	int	Number of DWords to read.	required

Returns:

Type	Description
list[int]	List of unsigned 32-bit integers.

read_dwords_single_request(client, device, count) async

Read contiguous dword values using one high-level logical operation.

Dword arrays always use one protocol request; there is no switch that can silently enable splitting.

read_named(client, addresses) async

Read named entries in declaration order as one non-atomic FIFO operation.

The returned dictionary preserves the original address strings as keys so application code can display or diff read results without rebuilding the request list.

Address format examples:

• "P1-D0100:U": unsigned 16-bit int
• "P1-D0100:F": float32
• "P1-D0100:S": signed 16-bit int
• "P1-D0100:D": unsigned 32-bit int
• "P1-D0100:L": signed 32-bit int
• "P1-D0100.3": bit 3 within one word (bool)

Parameters:

Name	Type	Description	Default
client	AsyncToyopucDeviceClient	Connected AsyncToyopucDeviceClient.	required
addresses	list[str]	Non-empty list of unique named addresses.	required

Returns:

Type	Description
dict[str, int | float | bool]	Dictionary mapping each address string to its value.

read_typed(client, device, dtype) async

Read one device value and convert it to the specified Python type.

Supported dtype codes are "U", "S", "D", "L", and "F". The helper keeps the public surface aligned with the .NET and C++ helper layers.

Parameters:

Name	Type	Description	Default
client	AsyncToyopucDeviceClient	Connected AsyncToyopucDeviceClient.	required
device	str	Device address string (e.g. "P1-D0100", "B0000").	required
dtype	str	Type code. "U" for unsigned 16-bit int, "S" for signed 16-bit int, "D" for unsigned 32-bit int, "L" for signed 32-bit int, "F" for float32.	required

Returns:

Type	Description
int | float	Converted value as int or float.

read_words(client, device, count) async

Read count contiguous word values starting at device.

Parameters:

Name	Type	Description	Default
client	AsyncToyopucDeviceClient	Connected AsyncToyopucDeviceClient.	required
device	str	Starting device address string, e.g. "P1-D0100".	required
count	int	Number of words to read.	required

Returns:

Type	Description
list[int]	List of unsigned 16-bit integers.

read_words_single_request(client, device, count) async

Read contiguous word values using one high-level logical operation.

This name is retained as an explicit statement of the operation's single-request contract.

write_bit_in_word(client, device, bit_index, value) async

Set or clear a single bit within a word device (read-modify-write).

This helper is intended for expressions such as "P1-D0100.3". Direct bit devices should be written through :func:write_typed or the lower-level client API.

Parameters:

Name	Type	Description	Default
client	AsyncToyopucDeviceClient	Connected AsyncToyopucDeviceClient.	required
device	str	Word device address.	required
bit_index	int	Bit position within the word, in the range 0 to 15.	required
value	bool	New bit state. This must be an actual bool.	required

write_dwords_single_request(client, device, values) async

Write contiguous dword values using one high-level logical operation.

Dword arrays always use one protocol request; there is no switch that can silently enable splitting.

write_typed(client, device, dtype, value) async

Write one device value using the specified type format.

The dtype codes match :func:read_typed. Word-sized values are written as one logical word, while "D", "L", and "F" use the dedicated 32-bit helper paths.

Parameters:

Name	Type	Description	Default
client	AsyncToyopucDeviceClient	Connected AsyncToyopucDeviceClient.	required
device	str	Device address string.	required
dtype	str	Type code accepted by :func:read_typed.	required
value	int | float	Value to write.	required

write_words_single_request(client, device, values) async

Write contiguous word values using one high-level logical operation.

This helper is intended for ranges that should remain one logical write from the caller's perspective.

try_parse_device_address(device, *, profile)

Return parsed address information, or None when parsing fails.

parse_address(text, unit)

Parse address strings like 'D0100', 'D0100L', 'M0201'.

Notes: - The manual examples use hexadecimal numeric fields (e.g. D0100 -> 0x0100). - Device numeric fields always use canonical hexadecimal notation.

parse_prefixed_address(text, unit)

Parse a prefixed address and return (program_ex_no, parsed_address).

Examples: - P1-M1000 - P2-D2000L - P3-X0010H

The returned ex_no is the prefix-side program exchange number used by prefixed access paths. The second value is a normal ParsedAddress.

encode_word_address(addr)

Encode a basic-area word address into the numeric protocol address.

This is used for normal word commands such as CMD=1C/1D. For bit-device families, ...W notation is accepted and mapped to the corresponding word address.

encode_byte_address(addr)

Encode a basic-area byte address into the numeric protocol address.

This is used for normal byte commands such as CMD=1E/1F. For bit-device families, ...L and ...H are treated as W/H/L addressing.

encode_bit_address(addr)

Encode a basic-area bit address into the numeric protocol address.

This is used for normal bit commands such as CMD=20/21.

encode_program_word_address(addr)

Encode a prefixed (P1/P2/P3) word address for CMD=94/95.

This also supports ...W addressing on prefixed bit-device families.

encode_program_byte_address(addr)

Encode a prefixed (P1/P2/P3) byte address for CMD=96/97.

This also supports ...L / ...H addressing on prefixed bit-device families.

encode_program_bit_address(addr)

Encode a prefixed (P1/P2/P3) bit address for CMD=98/99.

Returns (bit_no, addr) where bit_no is the bit position inside the addressed byte/word group and addr is the 16-bit monitor address field.

encode_exno_bit_u32(ex_no, bit_addr)

Encode a PC10 32-bit bit address from exchange number and bit address.

encode_exno_byte_u32(ex_no, byte_addr)

Encode a PC10 32-bit byte address from exchange number and byte address.

split_u32_words(value)

Split a 32-bit value into (low_word, high_word).

encode_ext_no_address(area, index, unit)

Encode an extended-area address into (No., 16-bit address).

This is the main helper for CMD=94-99 on areas such as: - ES, EN, H - U, EB - extended bit-device families when they are addressed by word/byte form

Note: - real-hardware FR word access uses encode_fr_word_addr32() with CMD=C2/C3, not CMD=94-99

fr_block_ex_no(index)

Return the FR block Ex No. for a word index.

FR is organized in 0x8000-word blocks. The manual's FR registration command (CMD=CA) uses the block Ex No. in the range 0x40-0x7F.

encode_fr_word_addr32(index)

Encode an FR word index for PC10 block access (CMD=C2/C3).

Real hardware FR access uses PC10 block read/write with: - high word: FR block Ex No. (0x40-0x7F) - low word: byte offset inside the 0x8000-word block

parse_relay_hops(text)

Parse relay hops using decimal-only component or direct-link notation.

normalize_relay_hops(hops)

Normalize relay hops from text or (link, station) pairs.

format_relay_hop(link, station)

Format one relay hop in the preferred P1-L2:N2 style.

resolve_device(device, *, profile)

Resolve an address and bind the result to one canonical PLC profile.

display_name(profile)

Return the canonical human-readable display name for a PLC profile.

plc_profile_descriptors()

Return presentation and connection metadata for every canonical PLC profile.