Class: Tag

Tag

Provides methods for interacting with a single tag on an EtherNet/IP server.

The tag can be read using read, or written using write. These methods can also be used to read/write only a part of the tag if the tag is a UDT.

If the value of a tag changes at the server, the change will not be automatically sent. Instead, read must be called periodically if it must be kept up to date. autoRead is available to make this easier.

Similarly, changes made to tags on the client will not be written to the server until write is called. autoWrite is available to simplify this.

Members


autoRead :number

Gets/sets the number of milliseconds between automatic reads of the tag.

Because changes are not automatically pushed from the server to the client, read must be called periodically to keep the value of a tag in sync with the server. When this value is greater than 0, read will be called automatically using the specified interval.

Set to 0 to disable automatic reads.

Type:
  • number
Since:
  • 1.0 (WAT 2.2)
Default Value:
  • 0

autoWrite :bool

Gets/sets if automatic writing is enabled.

When automatic writing is enabled, every time the value of the tag (or the value of a property when the tag is a UDT) changes, the changed value will be written to the server. If the changed value is a property of a UDT, then only the property will be written (as opposed to the entire UDT). This can be convenient when the application does not want to manage calls to write. However, if many properties change at once, or if a property value changes rapidly, this will result in many small write commands to the server which can be inefficient. In this case, the application should decide when and what is appropriate to write.

Type:
  • bool
Since:
  • 1.0 (WAT 2.2)
Default Value:
  • false
See:

<readonly> data :cip.CIPVar

Gets a cip object that represent the value of the tag.

If the tag is a UDT type, this object will be a cip.UDT, and the properties will be available as children. If the tag is a primitive type, this object will be the corresponding cip type (e.g. cip.Number), where the value is typically accessible via the value property (e.g. cip.Number#value).

Type:
Since:
  • 1.0 (WAT 2.2)

<readonly> error :string

Gets a description of the last error that occurred.

Errors may occur during automatic or explicit reads/writes/loads. errorChanged will be emitted whenever an error occurs (even if the string is the same as the previous error). Because this property only holds the value of the last error, it is typically only used during debugging, or in conjunction with errorChanged, which is often more useful.

Type:
  • string
Since:
  • 1.0 (WAT 2.2)

<readonly> loaded :bool

Gets a value indicating if the tag has been successfully loaded.

A tag is successfully loaded when the structure and value has been read from the server. When true, the data property can be used to read/write the tag value. When a tag is loaded (either automatically due to a server changed, or explicitly via eipc.Tag#load), the data object is destroyed and re-created. Thus, any connections that were made to the previous object must be re-established using the new object.

Type:
  • bool
Since:
  • 1.0 (WAT 2.2)

Methods


load()

Loads the structure and value of the tag from the server.

This function is automatically called when the tag is created (or when a connection is established to the server), after a connection is restored, and when something changes on the server that requires a refresh. Therefore, it typically does not need to be explicitly called by the application unless the application is aware of additional events that require a re-load.

Calling this will result in data being re-created. See loaded for more details.

When called (automatically or explicitly), either loadedChanged or loadFailure will be emitted to indicate that the load is complete.

Since:
  • 1.0 (WAT 2.2)

read( [object])

Reads the value of the specified property (or the entire tag if no property is specified)

If it is desired to keep a tag value up to date with the value on the server, this method must be called periodically. Alternatively, autoRead can be used.

When called (automatically or explicitly), either readSuccess or readFailure will be emitted to indicate that the read is complete.

Parameters:
Name Type Argument Default Description
object cip.CIPVar <optional>
null

The object to read

Since:
  • 1.0 (WAT 2.2)

write( [object])

Writes the value of the specified property (or the entire tag if no property is specified) to the server.

After a property has been locally changed, it must be written back to the server using this function if it is desired to update the server. Alternatively, autoWrite can be used.

When called (automatically or explicitly), either writeSuccess or writeFailure will be emitted to indicate that the write is complete.

Parameters:
Name Type Argument Default Description
object cip.CIPVar <optional>
null

The object to write

Since:
  • 1.0 (WAT 2.2)

writeOnChange(object [, enabled])

Enables/disables automatic writing when a specific property changes.

When the tag is a UDT, autoWrite enables/disables automatic writing for all UDT properties. This method provide finer control by allowing the autoWrite state of individual properties to be enabled/disabled. If the specified property contains properties (e.g. it is a UDT), then the setting will be applied to all of the contained properties as well.

Parameters:
Name Type Argument Default Description
object cip.CIPVar

The object to apply the setting to

enabled bool <optional>
true

Whether to enable or disable automatic writes

Since:
  • 1.0 (WAT 2.2)

Events


errorChanged

Emitted when an error occurs. See error for more details.

Parameters:
Name Type Description
description string

The error that occurred

Since:
  • 1.0 (WAT 2.2)

loadedChanged

Emitted when the eipc.Tag#loaded property changes.

Since:
  • 1.0 (WAT 2.2)

loadFailed

Emitted when the eipc.Tag#load is called and fails.

Since:
  • 1.0 (WAT 2.2)

readFailure

Emitted after a failed read.

Parameters:
Name Type Description
object cip.CIPVar

The object that failed to read

description string

The error that occurred

Since:
  • 1.0 (WAT 2.2)

readSuccess

Emitted after a successful read.

Parameters:
Name Type Description
object cip.CIPVar

The object read

Since:
  • 1.0 (WAT 2.2)

writeFailure

Emitted after a failed write.

Parameters:
Name Type Description
object cip.CIPVar

The object that failed to write

description string

The error that occurred

Since:
  • 1.0 (WAT 2.2)

writeSuccess

Emitted after a successful write.

Parameters:
Name Type Description
object cip.CIPVar

The object written

Since:
  • 1.0 (WAT 2.2)