Application Layer#

icspacket.proto.dnp3.application.APDU_SEQ_MAX = 16#: Maximum border number of a sequence number within an APDU.

Added in version 0.2.0.

class icspacket.proto.dnp3.application.ApplicationControl(first_fragment: bool = False, final_fragment: bool = False, need_confirmation: bool = False, unsolicited_response: bool = False, sequence: int = 0)[source]#

Represents the DNP3 Application Control octet (See DNP3 Specification, §4.2.2.4).

This library models the octet as a bitfield so callers can read or set the fragmentation flags, the confirmation-request flag, and the rolling sequence number that accompany every application fragment exchanged between a master and an outstation.

first_fragment: bool = False#: True when this fragment is the first piece of a multi-fragment message.

final_fragment: bool = False#: True when this fragment is the last piece of a multi-fragment message.

need_confirmation: bool = False#: Requests that the peer’s Application Layer send back an Application Layer confirmation message once the fragment is processed.

unsolicited_response: bool = False#: True when the fragment is an unsolicited response (or the confirmation of one) rather than something the master asked for.

sequence: int = 0#: Rolling sequence number (wraps modulo 16) that this library uses to line up fragments belonging to the same message and to catch duplicates.

class icspacket.proto.dnp3.application.IIN(device_restart: bool = False, device_trouble: bool = False, local_control: bool = False, need_time: bool = False, class_3_events: bool = False, class_2_events: bool = False, class_1_events: bool = False, broadcast: bool = 0, reserved: int = 0, config_corrupt: bool = False, already_executing: bool = False, event_buffer_overflow: bool = False, parameter_error: bool = False, object_unknown: bool = False, no_func_code_support: bool = False)[source]#

Represents the DNP3 Internal Indications (IIN) bitfield (See DNP3 Specification, §4.2.2.6).

This library exposes the two-byte IIN field as individual boolean flags so callers can inspect an outstation’s status and error conditions - such as pending events, a recent restart, or an unsupported function code - without manually decoding the raw bits.

device_restart: bool = False#: Set by the outstation after it has restarted, so the master can notice that a reset happened since the last exchange.

device_trouble: bool = False#: Flags an abnormal condition on the outstation whose exact meaning is device-specific (vendor-defined).

local_control: bool = False#: Set when one or more of the outstation’s points are currently being driven by local control rather than by the master.

need_time: bool = False#: Set by the outstation to ask the master to perform time synchronization.

class_3_events: bool = False#: Set while the outstation is holding Class 3 events that have not yet been reported.

class_2_events: bool = False#: Set while the outstation is holding Class 2 events that have not yet been reported.

class_1_events: bool = False#: Set while the outstation is holding Class 1 events that have not yet been reported.

broadcast: bool = 0#: Set when the request that triggered this response was sent to the broadcast address.

config_corrupt: bool = False#: Set when the outstation finds its own configuration data to be corrupted; implementing this check is optional.

already_executing: bool = False#: Set when the outstation is still carrying out a previously requested operation of the same kind; support for this flag is optional.

event_buffer_overflow: bool = False#: Set when the outstation’s event buffer filled up and it had to discard at least one unconfirmed event.

parameter_error: bool = False#: Set when the outstation rejects the request because one of its parameters was invalid.

object_unknown: bool = False#: Set when the outstation cannot recognize or does not implement one or more of the objects referenced by the request.

no_func_code_support: bool = False#: Set when the outstation has no implementation for the function code carried by the request.

class icspacket.proto.dnp3.application.APDU(control: ApplicationControl = <factory>, function: FunctionCode | int = FunctionCode.CONFIRM, iin: IIN = None, objects: bytes = b'')[source]#

Represents the Application Protocol Data Unit (APDU) in DNP3 (See DNP3 Specification, §4.2.2).

This struct models one application-layer fragment, regardless of whether it was sent by a master or an outstation - both directions reuse the same on-the-wire layout of a control octet, a function code, an optional internal-indications field, and the encoded application objects that follow.

Changed in version 0.2.0: Added support for building an APDU using bytes(obj).

control: ApplicationControl#: The fragment’s control octet, modeled by ApplicationControl, holding the fragmentation/confirmation flags and the sequence number.

function: FunctionCode | int = 0#: Single-octet operation code carried by this fragment. Request codes fall in 0-128; response codes fall in 129-255.

iin: IIN = None#

Outstation status/error flags, modeled by IIN.

Only response fragments carry this field, so it is left unset while decoding requests; parsing it is conditional on the function code indicating a response (≥ 129).

objects: bytes = b''#

Raw encoded application objects making up this fragment’s payload.

This library keeps the objects as opaque bytes here; use the object-header parsing helpers to decode individual entries.

static from_octets(octets: bytes)[source]#: Parse an APDU from a raw byte sequence.

icspacket.proto.dnp3.const.APDU_REQ_FUNC_MIN = 0#: Minimum function code value for Application Layer requests.

icspacket.proto.dnp3.const.APDU_REQ_FUNC_MAX = 128#: Maximum function code value for Application Layer requests.

icspacket.proto.dnp3.const.APDU_RESP_FUNC_MIN = 129#: Minimum function code value for Application Layer responses.

icspacket.proto.dnp3.const.APDU_RESP_FUNC_MAX = 255#: Maximum function code value for Application Layer responses.

class icspacket.proto.dnp3.const.FunctionCode(*values)[source]#

Application Layer Function Codes.

Each member identifies one operation a master or outstation can invoke on its peer; this library writes the member’s numeric value into the first octet of an Application Protocol Data Unit (APDU) to say which operation a given fragment represents.

(See DNP3 Specification, Section 4.2.2.5)

CONFIRM = 0#: Sent by the master to acknowledge that it received an application fragment.

READ = 1#: Asks the outstation to return the data identified in the request.

WRITE = 2#: Asks the outstation to store the data supplied in the request.

SELECT = 3#: Has the outstation prepare the requested output points, the first step of a select-before-operate sequence completed by OPERATE.

OPERATE = 4#: Tells the outstation to activate the output points a prior SELECT already prepared.

DIRECT_OPERATE = 5#: Tells the outstation to activate the named output points right away, skipping the SELECT step.

DIRECT_OPERATE_NR = 6#: Behaves like DIRECT_OPERATE, except the outstation does not send back a response.

IMMED_FREEZE = 7#: Tells the outstation to snapshot its current data values into a freeze buffer.

IMMED_FREEZE_NR = 8#: Behaves like IMMED_FREEZE, except the outstation does not send back a response.

FREEZE_CLEAR = 9#: Tells the outstation to snapshot its data values into a freeze buffer and then reset the originals.

FREEZE_CLEAR_NR = 10#: Behaves like FREEZE_CLEAR, except the outstation does not send back a response.

FREEZE_AT_TIME = 11#: Schedules the outstation to freeze its data values at a time or on an interval given in the request.

FREEZE_AT_TIME_NR = 12#: Behaves like FREEZE_AT_TIME, except the outstation does not send back a response.

COLD_RESTART = 13#: Asks the outstation to fully reset both its hardware and software.

WARM_RESTART = 14#: Asks the outstation to perform a lighter, partial reset of the device.

INITIALIZE_DATA = 15#: Obsolete; new designs must not send this code.

INITIALIZE_APPL = 16#: Asks the outstation to bring the named application(s) into a ready-to-run state.

START_APPL = 17#: Asks the outstation to start the application(s) named in the request.

STOP_APPL = 18#: Asks the outstation to stop the application(s) named in the request.

SAVE_CONFIG = 19#: Deprecated request to save configuration; avoid using it in new designs.

ENABLE_UNSOLICITED = 20#: Asks the outstation to start sending unsolicited responses for the named points.

DISABLE_UNSOLICITED = 21#: Asks the outstation to stop sending unsolicited responses for the named points.

ASSIGN_CLASS = 22#: Asks the outstation to assign the named points or events to one of its event classes.

DELAY_MESSAGE = 23#: Asks the outstation to report how much processing/transmission delay it is adding.

RECORD_CURRENT_TIME = 24#: Asks the outstation to note its own clock value at the instant it receives this request’s last octet.

OPEN_FILE = 25#: Asks the outstation to open the file named in the request.

CLOSE_FILE = 26#: Asks the outstation to close a previously opened file.

DELETE_FILE = 27#: Asks the outstation to delete the file named in the request.

GET_FILE_INFO = 28#: Asks the outstation to report information describing a file.

AUTHENTICATE_FILE = 29#: Asks the outstation to return a key used to authenticate file access.

ABORT_FILE = 30#: Asks the outstation to cancel a file transfer already in progress.

ACTIVATE_CONFIG = 31#: Asks the outstation to switch to (activate) a previously loaded configuration.

AUTHENTICATE_REQ = 32#: Sent by the master to start an authentication exchange that expects an acknowledgement.

AUTH_REQ_NO_ACK = 33#: Sent by the master to start an authentication exchange that does not expect an acknowledgement.

RESPONSE = 129#: Marks a fragment as the outstation’s reply to a master’s request.

UNSOLICITED_RESPONSE = 130#: Marks a fragment as a response the outstation generated on its own, with no matching request from the master.

AUTHENTICATE_RESP = 131#: Sent by the outstation to answer a master’s authentication request.

class icspacket.proto.dnp3.const.ObjectPrefixCode(*values)[source]#

Object Prefix Codes.

Selects how this library tags each object inside an encoded Application Layer message - with an index value, a size value, or no prefix at all. (See DNP3 Specification, Section 4.2.2.7.3.2)

NONE = 0#: No prefix is written before each object.

INDEX_8 = 1#: Each object is preceded by an 8-bit index value.

INDEX_16 = 2#: Each object is preceded by a 16-bit index value.

INDEX_32 = 3#: Each object is preceded by a 32-bit index value.

OBJECT_SIZE_8 = 4#: Each object is preceded by its own size, encoded in 8 bits.

OBJECT_SIZE_16 = 5#: Each object is preceded by its own size, encoded in 16 bits.

OBJECT_SIZE_32 = 6#: Each object is preceded by its own size, encoded in 32 bits.

RESERVED = 7#: Reserved for future use.

class icspacket.proto.dnp3.const.RangeSpecifierCode(*values)[source]#

Range Specifier Codes.

Selects how this library encodes which objects a qualifier field addresses - as a start/stop index pair, a start/stop virtual-address pair, or a plain object count. (See DNP3 Specification, Section 4.2.2.7.3.3)

RANGE_8 = 0#: Range field holds a pair of 1-octet start/stop index values.

RANGE_16 = 1#: Range field holds a pair of 2-octet start/stop index values.

RANGE_32 = 2#: Range field holds a pair of 4-octet start/stop index values.

RANGE_8_VIRTUAL = 3#: Range field holds a pair of 1-octet start/stop virtual addresses.

RANGE_16_VIRTUAL = 4#: Range field holds a pair of 2-octet start/stop virtual addresses.

RANGE_32_VIRTUAL = 5#: Range field holds a pair of 4-octet start/stop virtual addresses.

NONE = 6#: No range field follows; the request/response covers every value.

COUNT_8 = 7#: Range field holds a single 1-octet object count instead of a start/stop pair.

COUNT_16 = 8#: Range field holds a single 2-octet object count instead of a start/stop pair.

COUNT_32 = 9#: Range field holds a single 4-octet object count instead of a start/stop pair.

VARIABLE = 11#: Free-format qualifier whose range field is a single 1-octet object count.