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_connectread_typed/write_typedread_words_single_request/read_dwords_single_requestread_words_chunked/read_dwords_chunkedwrite_bit_in_wordread_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__ = '1.2.0'
module-attribute
__all__ = ['ToyopucClient', 'AsyncToyopucClient', 'AsyncToyopucDeviceClient', 'ToyopucDeviceClient', 'ResolvedDevice', 'ClockData', 'CpuStatusData', 'RelayLayer', 'ToyopucError', 'ToyopucProtocolError', 'ToyopucTimeoutError', 'ToyopucTraceDirection', 'ToyopucTraceFrame', 'ToyopucConnectionOptions', 'ToyopucAddress', 'format_device_address', 'normalize_address', 'open_and_connect', 'parse_device_address', 'poll', 'read_dwords', 'read_dwords_chunked', 'read_dwords_single_request', 'read_named', 'read_typed', 'read_words', 'read_words_chunked', 'read_words_single_request', 'write_bit_in_word', 'write_dwords_chunked', 'write_dwords_single_request', 'write_typed', 'write_words_chunked', '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', 'ToyopucAddressingOptions', 'ToyopucAreaDescriptor', 'ToyopucDeviceCatalog', 'ToyopucDeviceMatrixRow', 'ToyopucPlcProfile', 'ToyopucPlcProfiles', 'display_name']
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.
last_tx
property
Last raw frame transmitted by this client, if available.
last_rx
property
Last raw frame received by this client, if available.
connect()
Open the configured TCP or UDP socket if it is not already open.
close()
Close the current socket and clear transport state.
send_raw(cmd, data=b'')
Send one raw command code and payload, returning the parsed response frame.
send_payload(payload)
Send a fully-built command payload and return the parsed response.
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.
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.
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 PC10 block read (CMD=C2).
FR real-hardware access uses 32-bit PC10 addressing with
Ex No.=0x40-0x7F, not CMD=94.
write_fr_words(index, values, *, commit=False)
Write FR words via PC10 block write (CMD=C3).
This updates the FR work area. Persisting the block to flash requires
CMD=CA. Set commit=True to commit every affected FR block after the
write completes.
write_fr_words_ex(index, values, *, commit=False, wait=False, timeout=30.0, poll_interval=0.2)
Write FR words, with optional commit and completion wait.
When commit=True, this follows the manual's 64-kbyte block unit:
each affected FR block is written with C3, committed with CA, and
optionally waited on before moving to the next block.
commit_fr_block(index, *, wait=False, timeout=30.0, poll_interval=0.2)
Commit the FR block containing index via CMD=CA.
By default this waits until Data7.bit4 (under_writing_flash_register)
clears and raises on Data7.bit5 (abnormal_write_flash_register).
commit_fr_range(index, count=1, *, wait=False, timeout=30.0, poll_interval=0.2)
Commit every FR block touched by a contiguous word range.
write_fr_words_committed(index, values)
Write FR words and commit every affected FR block.
fr_register(ex_no)
Issue the FR-register command 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)
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, *, commit=False)
Write FR words through relay hops, optionally committing touched blocks.
relay_write_fr_words_ex(hops, index, values, *, commit=False, wait=False, timeout=30.0, poll_interval=0.2)
Write FR words through relay hops, with optional commit and completion wait.
relay_fr_register(hops, ex_no)
Issue the FR-register command CMD=CA through relay hops.
relay_commit_fr_block(hops, index, *, wait=False, timeout=30.0, poll_interval=0.2)
Commit the remote FR block containing index via relay CMD=CA.
relay_commit_fr_range(hops, index, count=1, *, wait=False, timeout=30.0, poll_interval=0.2)
Commit every FR block touched by a contiguous relay FR range.
relay_wait_fr_write_complete(hops, *, timeout=30.0, poll_interval=0.2)
Poll remote FR flash-write completion status through relay hops.
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.
wait_fr_write_complete(*, timeout=30.0, poll_interval=0.2)
Poll FR flash-write completion status.
Prefer CMD=A0 / 00 11 00 when available. If the target rejects A0
with an invalid-subcommand style error, fall back to normal CPU status
CMD=32 / 11 00, which exposes the same Data7 flash-write bits on
the Nano 10GX tested in this project.
write_clock(value)
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.
AsyncToyopucClient
Bases: _AsyncToyopucClientBase
Async wrapper for the low-level TOYOPUC client.
AsyncToyopucDeviceClient
Bases: _AsyncToyopucClientBase
Async wrapper for the high-level TOYOPUC client.
ToyopucDeviceClient
Bases: ToyopucClient
High-level client that accepts string device addresses.
resolve_device(device)
Resolve a string address into a ResolvedDevice.
relay_read(hops, device, count=1)
Read one item or a contiguous sequence through relay hops.
relay_write(hops, device, value)
Write one item or a contiguous sequence through relay hops.
relay_read_words(hops, device, count=1)
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_many(hops, devices)
Read multiple devices through relay hops as one compatible protocol request.
relay_write_many(hops, items)
Write multiple devices through relay hops as one compatible protocol request.
read_fr(device, count=1)
Read one or more FR words using the dedicated FR path.
relay_read_fr(hops, device, count=1)
Read one or more FR words through relay hops.
write_fr(device, value, *, commit=False, wait=None, timeout=30.0, poll_interval=0.2)
Write one or more FR words, optionally committing and waiting.
relay_write_fr(hops, device, value, *, commit=False, wait=None, timeout=30.0, poll_interval=0.2)
Write one or more FR words through relay hops, optionally committing.
commit_fr(device, count=1, *, wait=False, timeout=30.0, poll_interval=0.2)
Commit every FR block touched by the given FR word range.
relay_commit_fr(hops, device, count=1, *, wait=False, timeout=30.0, poll_interval=0.2)
Commit every FR block touched by the given FR word range through relay hops.
read(device, count=1)
Read one item or a contiguous sequence from a device address.
write(device, value)
Write one item or a contiguous sequence to a device address.
read_many(devices)
Read multiple devices as one compatible protocol request and preserve input order.
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, *, atomic_transfer=False)
Read one or more 32-bit values from consecutive word devices.
write_dwords(device, values, *, atomic_transfer=False)
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, *, atomic_transfer=False)
Read one or more IEEE-754 float32 values from consecutive word devices.
write_float32s(device, values, *, atomic_transfer=False)
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, *, atomic_transfer=False)
Read one or more 32-bit values through relay hops.
relay_write_dwords(hops, device, values, *, atomic_transfer=False)
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, *, atomic_transfer=False)
Read one or more IEEE-754 float32 values through relay hops.
relay_write_float32s(hops, device, values, *, atomic_transfer=False)
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 |
year_2digit |
int
|
Lower two digits of the year. |
weekday |
int
|
PLC weekday value where |
as_datetime(*, year_base=2000)
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.
ToyopucProtocolError
Bases: ToyopucError
Raised when the response frame is invalid or unexpected.
ToyopucTimeoutError
Bases: ToyopucProtocolError
Raised on socket timeouts.
ToyopucTraceDirection
Bases: Enum
Direction for a traced TOYOPUC computer-link frame.
ToyopucTraceFrame
dataclass
One raw TOYOPUC frame observed by a trace hook.
ToyopucConnectionOptions
dataclass
Stable connection settings for one TOYOPUC session.
Attributes:
| Name | Type | Description |
|---|---|---|
host |
str
|
PLC hostname or IP address. |
port |
int
|
TOYOPUC computer-link port. |
local_port |
int
|
UDP source port. Leave zero for an ephemeral port. |
transport |
str
|
|
timeout |
float
|
Socket timeout in seconds. |
retries |
int
|
Number of retry attempts performed by the async client. |
retry_delay |
float
|
Delay between retry attempts, in seconds. |
recv_bufsize |
int
|
Socket receive buffer size used by the sync client. |
plc_profile |
str | None
|
Canonical PLC profile name such as
|
trace_hook |
Callable[[ToyopucTraceFrame], None] | None
|
Optional callback invoked for sent and received frames. |
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.
ToyopucAddressingOptions
dataclass
Flags that control how device addresses are routed to protocol commands.
All flags default to True (Generic / PC10G mode behaviour).
Attributes:
| Name | Type | Description |
|---|---|---|
use_upper_u_pc10 |
bool
|
Route U-area indexes >= 0x08000 via PC10 block commands instead of ext-word commands. |
use_eb_pc10 |
bool
|
Route EB-area via PC10 block commands. |
use_fr_pc10 |
bool
|
Route FR-area via PC10 block commands. |
use_upper_bit_pc10 |
bool
|
Route P/V/T/C/L-area bit indexes >= 0x1000 (and derived word/byte >= 0x100) via PC10 block commands. |
use_upper_m_bit_pc10 |
bool
|
Same as above but for M-area. |
from_profile(profile)
staticmethod
Return addressing options associated with a canonical PLC profile.
ToyopucAreaDescriptor
dataclass
Per-area metadata for a PLC profile.
Attributes:
| Name | Type | Description |
|---|---|---|
area |
str
|
Area name (e.g. |
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.
ToyopucPlcProfiles
Catalog of all known TOYOPUC PLC profiles.
get_names()
classmethod
Return canonical PLC profile names known to the catalog.
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=None)
Return the canonical TOYOPUC device string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
device
|
str
|
User-facing device text such as |
required |
profile
|
str | None
|
Required canonical addressing profile used by
:func: |
None
|
Returns:
| Type | Description |
|---|---|
str
|
Canonical uppercase address text suitable for logs and configuration |
str
|
storage. |
open_and_connect(host, port=1025, timeout=3.0, retries=0, *, local_port=0, transport='tcp', retry_delay=0.2, recv_bufsize=UDP_RECEIVE_BUFFER_SIZE, plc_profile=None, trace_hook=None)
async
Create and connect an AsyncToyopucDeviceClient.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
host
|
str | ToyopucConnectionOptions
|
PLC IP address, hostname, or a
:class: |
required |
port
|
int
|
TOYOPUC computer-link port. Defaults to 1025. |
1025
|
local_port
|
int
|
UDP source port. Leave zero for an ephemeral port. |
0
|
transport
|
str
|
|
'tcp'
|
timeout
|
float
|
Socket timeout in seconds. |
3.0
|
retries
|
int
|
Retry count used by the async client. |
0
|
retry_delay
|
float
|
Delay between retry attempts, in seconds. |
0.2
|
recv_bufsize
|
int
|
Socket receive buffer size. |
UDP_RECEIVE_BUFFER_SIZE
|
plc_profile
|
str | None
|
Canonical PLC profile name required by the high-level device client. |
None
|
trace_hook
|
Callable[[ToyopucTraceFrame], None] | None
|
Optional callback invoked for sent and received frames. |
None
|
Returns:
| Type | Description |
|---|---|
AsyncToyopucDeviceClient
|
A connected AsyncToyopucDeviceClient. |
parse_device_address(device, *, profile=None)
Parse user-facing TOYOPUC address notation.
Supported forms match :func:read_named:
"P1-D0100"as unsigned 16-bit word notation"P1-D0100:F"with explicit dtypeU/S/D/L/F"P1-D0100.A"for one bit inside a word
poll(client, addresses, interval)
async
Yield one named-device snapshot every interval seconds.
This helper performs repeated :func:read_named calls and sleeps for the
requested interval between snapshots.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client
|
AsyncToyopucDeviceClient
|
Connected AsyncToyopucDeviceClient. |
required |
addresses
|
list[str]
|
List containing exactly one address string. |
required |
interval
|
float
|
Poll interval in seconds. |
required |
Usage::
async for snapshot in poll(client, ["P1-D0100"], interval=1.0):
print(snapshot)
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_chunked(client, device, count, max_dwords_per_request=32)
async
Read contiguous dword values across multiple logical operations.
Chunk boundaries are aligned to full dwords so a 32-bit value is never torn across requests.
read_dwords_single_request(client, device, count)
async
Read contiguous dword values using one high-level logical operation.
The helper requests dwords through the client with atomic_transfer=True
so each logical 32-bit value stays intact.
read_named(client, addresses)
async
Read one device by address string and return the result as a dict.
The returned dictionary preserves the original address strings as keys so application code can display or diff snapshots without rebuilding the request list.
Address format examples:
"P1-D0100": 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]
|
List containing exactly one address string. |
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.
|
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. |
required |
count
|
int
|
Number of words to read. |
required |
Returns:
| Type | Description |
|---|---|
list[int]
|
List of unsigned 16-bit integers. |
read_words_chunked(client, device, count, max_words_per_request=64)
async
Read contiguous word values across multiple logical operations.
Chunking is explicit here. Use this helper only when the caller accepts multi-request read semantics.
read_words_single_request(client, device, count)
async
Read contiguous word values using one high-level logical operation.
This is the explicit atomic path for a contiguous word range. If the
caller wants multiple protocol requests, use :func:read_words_chunked.
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 |
required |
value
|
bool
|
New bit state. |
required |
write_dwords_chunked(client, device, values, max_dwords_per_request=32)
async
Write contiguous dword values across multiple logical operations.
Each chunk boundary is aligned to full dwords so one logical value remains intact inside one request.
write_dwords_single_request(client, device, values)
async
Write contiguous dword values using one high-level logical operation.
The helper uses atomic_transfer=True so the logical dword range is
written through the dedicated dword API instead of implicit word pairs.
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: |
required |
value
|
int | float
|
Value to write. |
required |
write_words_chunked(client, device, values, max_words_per_request=64)
async
Write contiguous word values across multiple logical operations.
Use this helper only when multiple write operations are acceptable to the caller.
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=None)
Return parsed address information, or None when parsing fails.
parse_address(text, unit, *, radix=16)
Parse address strings like 'D0100', 'D0100L', 'M0201'.
Notes: - The manual examples use hexadecimal numeric fields (e.g. D0100 -> 0x0100). - Use radix=10 if your PLC uses decimal notation.
parse_prefixed_address(text, unit, *, radix=16)
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 from P1-L2:N2 or 0x12:0x0002 style text.
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, options=None, profile=None)
Resolve a string device address into a normalized access descriptor.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
device
|
str
|
Device address string (e.g. |
required |
options
|
ToyopucAddressingOptions | None
|
Optional addressing option flags that control PC10 routing. When omitted, the selected profile's options are used. |
None
|
profile
|
str | None
|
Required canonical PLC profile name (e.g.
|
None
|
display_name(profile)
Return the canonical human-readable display name for a PLC profile.