Modbus TCP

Warning

The Modbus functionality is under development and may be subject to change. Note that Modbus features are only supported from version 0.27.0.

Overview

Evolabel printers provide a Modbus TCP Server interface which can be accessed on port 502. Only one client connection at a time is allowed. All Modbus addresses in this documentation are 1-based, and offsets are 0-based from their respective register bank.

Supported Function Codes

FC 1 Read Discrete Output Coils
The output coil registers 00001-00004 can be read using a single Modbus transaction.
FC 2 Read Discrete Input Contacts
The discrete input registers 10001-10006 can be read using a single Modbus transaction.
FC 3 Read Multiple Holding Registers
It is only supported to read one register at a time. Most holding registers map to unique function calls that are not useful to group together in a single transaction.
FC 4 Read Input Registers
The modbus registers 30001-30080 can be read using a single Modbus transaction.
FC 5 Write Single Discrete Output Coil
Set the state of a single hardware output port.
FC 6 Write Single Register
Trigger a function call.
FC 15 Write Multiple Discrete Output Coils
Set the state of multiple hardware output ports 00001-00006 in a single transaction.
FC 16 Write Multiple Registers
It is only supported to write one register at a time. Most holding registers map to unique function calls that are not useful to group together in a single transaction.

Discrete Output Coils

Address Name Description
00001 RW_IO_O1 Read/Write state of O1
00002 RW_IO_O2 Read/Write state of O2
00003 RW_IO_O3 Read/Write state of O3
00004 RW_IO_O4 Read/Write state of O4

Discrete Input Contacts

Address Name Description
10001 RD_IO_IN1 Read state of IN1
10002 RD_IO_IN2 Read state of IN2
10003 RD_IO_IN3 Read state of IN3
10004 RD_IO_IN4 Read state of IN4
10005 RD_IO_TRIG1 Read state of TRIG1
10006 RD_IO_TRIG2 Read state of TRIG2

Input Registers

Address Name Description
30001 RD_MARKER_STATE Current state of the marker
30005 RD_SEQUENCE_STATE Read current sequence state
30008 RD_SEQUENCE_RESULT Read last finished sequence result
30010 RD_APPLICATOR_STATE Current state of the applicator
30015 RD_PRINTER_STATE Current state of the printer
30020 RD_MESSAGES_ALARMS Read currently active alarms
30021 RD_MESSAGES_WARNINGS Read currently active warnings
30025 RD_JOB_STATE Get job availability
30031 RD_STAND1_POS Stand 1 position in mm
30032 RD_STAND2_POS Stand 2 position in mm
30033 RD_STAND3_POS Stand 3 position in mm
30041 RD_SCANNER1_RESULT Scanner 1 read data (32 registers, 64 ASCII characters)
30081 RD_SCANNER2_RESULT Scanner 2 read data (32 registers, 64 ASCII characters)
30121 RD_SCANNER3_RESULT Scanner 3 read data (32 registers, 64 ASCII characters)

Holding Registers

Address Name Description
40001 WR_MARKER_STATE Set the printer online or offline
40002 WR_API_HEARTBEAT_TIMEOUT Require WR_API_HEARTBEAT
40003 WR_API_HEARTBEAT Ensure printer that Modbus client is alive
40005 WR_SEQUENCE_PRINT Print active job immediately
40006 WR_SEQUENCE_APPLY Apply label with specified apply sequence
40007 WR_SEQUENCE_ABORT Abort the current product sequence
40008 WR_SEQUENCE_FINISH Indicate that current product sequence is finished
40020 WR_MESSAGES_RESET Reset active alarms
40025 WR_JOB_CLEAR Clear all jobs
40030 WR_STAND_STOP Stop specified stands
40031 WR_STAND1_GOTO_MM Goto stand position in mm
40032 WR_STAND2_GOTO_MM Goto stand position in mm
40033 WR_STAND3_GOTO_MM Goto stand position in mm
40034 WR_STAND1_GOTO_STORED_POS Goto stored position
40035 WR_STAND2_GOTO_STORED_POS Goto stored position
40036 WR_STAND3_GOTO_STORED_POS Goto stored position

Motorized Stands

Motorized Stands are controlled by addressing a stand number. The stand number is shown in the user interface under Peripherals -> Motorized Stand.

Discrete Output Coils

The state of hardware output ports can be read and set by reading and writing to the corresponding address.


RW_IO_O1

Description Address Offset
Read/Write state of O1 00001 0x00
Value Description
0 Inactive
1 Active

RW_IO_O2

Description Address Offset
Read/Write state of O2 00002 0x01
Value Description
0 Inactive
1 Active

RW_IO_O3

Description Address Offset
Read/Write state of O3 00003 0x02
Value Description
0 Inactive
1 Active

RW_IO_O4

Description Address Offset
Read/Write state of O4 00004 0x03
Value Description
0 Inactive
1 Active

Discrete Inputs

The state of hardware input ports can be read by reading the corresponding address.


RD_IO_IN1

Description Address Offset
Read state of IN1 10001 0x00
Value Description
0 Inactive
1 Active

RD_IO_IN2

Description Address Offset
Read state of IN2 10002 0x01
Value Description
0 Inactive
1 Active

RD_IO_IN3

Description Address Offset
Read state of IN3 10003 0x02
Value Description
0 Inactive
1 Active

RD_IO_IN4

Description Address Offset
Read state of IN4 10004 0x03
Value Description
0 Inactive
1 Active

RD_IO_TRIG1

Description Address Offset
Read state of TRIG1 10005 0x04
Value Description
0 Inactive
1 Active

RD_IO_TRIG2

Description Address Offset
Read state of TRIG2 10006 0x05
Value Description
0 Inactive
1 Active

Input Registers


RD_MARKER_STATE

Description Address Offset
Current state of the marker 30001 0x00
Value Description
0b0000000000000001 (1) Offline
0b0000000000000010 (2) Online
0b0000000000000110 (6) Stopping
0b0000000000001001 (9) Alarm
0b0000000000010000 (16) Test
0b1000000000000000 (32768) Stand Position Changed

The lower bits of the register holds the current marker state. This is a bitfield where each bit indicates one of the states "offline", "online", "stopping", "alarm" and "test".

Note that "stopping" is a substate to "online" and "alarm" is a substate to "offline". Those states will have the bit representing their superstate set as well.

The upper bits are used for indicating state changes and that more information can be read in other registers. The upper bits are cleared on read.

b15: Updated information in any of RD_STAND1_POS, RD_STAND2_POS, or RD_STAND3_POS


RD_SEQUENCE_STATE

Description Address Offset
Read current sequence state 30005 0x04
Value Description
0b0000000000000000 (0) idle
0b0000000000000001 (1) printing
0b0000000000000010 (2) wait_apply
0b0000000000000011 (3) applying
0b0000000000000100 (4) ok_wait_next
0b0000000000001000 (8) error_wait_resume
0b0000000000001111 (15) State mask
0b0000000011110000 (240) Label index mask

Get the current print and apply sequence state. This is useful for high level tracking of print and apply sequences.

The register is divided into two parts: state, and label index.

../_images/modbus-sequence.png

Note

Some states are transient (will only be active during a very brief time), so a PLC program must handle that e.g. after printing, the next state wait_apply is never read, but the state will transfer directly to applying, as shown in the examples below.

Example: Triggering a single label print and apply cycle with a normal sequential sequence


Example: Triggering a dual label print and apply cycle with a normal sequential sequence


Example: Externally controlled print and apply cycle



RD_SEQUENCE_RESULT

Description Address Offset
Read last finished sequence result 30008 0x07
Value Description
0b0000000000000001 (1) Success
0b0100000000000000 (16384) Data valid
0b1000000000000000 (32768) Data loss

Read the result of the last finished sequence (either successfully finished, or aborted). b0 contains the result when b14 is 1.

Success
When Data valid is set, this bit represents the success of the last sequence. Automatically cleared upon read.
Data valid
Set when a sequence is finished or aborted. Automatically cleared upon read.
Data loss
Unread data was overwritten by new state changes. Automatically cleared upon read.

Example: One successful sequence followed by one failed sequence (where state is from RD_SEQUENCE_STATE).



RD_APPLICATOR_STATE

Description Address Offset
Current state of the applicator 30010 0x09
Value Description
0b0000000000000001 (1) Nonblocking
0b0000000000000010 (2) Applying
0b0000000000010000 (16) Applicator Error
0b1000000000000000 (32768) Data loss

Get the current applicator state. This is valid both for test sequences and production sequences. Each bit represents one state, and multiple bits can be set simultaneously.

Nonblocking
The applicator is in a position that will not block products in front of it. This may include printing or service positions, and will always be 1 for some applicator types that never block.
Applying
The applicator is applying. Note that this state may be very short and can cause data loss for fast applicators.
Error
The applicator is in an error state.
Data loss
Unread data was overwritten by new state changes.

RD_PRINTER_STATE

Description Address Offset
Current state of the printer 30015 0x0E
Value Description
0b0000000000000001 (1) Label stabilizing
0b0000000000000010 (2) Print sequence is active
0b0000000000000100 (4) No print data
0b0000000000001000 (8) Trig blocking
0b0000000000010000 (16) Printer alarm
0b0000000000100000 (32) Soft inhibition
0b0000000001000000 (64) Applicator is active

Get the current printer state. This is valid both for test sequences and production sequences. Each bit represents one aspect, and multiple bits can be set simultaneously.

Note

A printout can only be started if all bits in this register is zero.

Label stabilizing
The label is printed but waits for mechanical stabilization before application can start. This is a transient state that is only active up to 200 ms.
Print sequence is active
Printer is printing, waiting for application to start, or backfeeding.
No print data
No print data is loaded to the printhead. If the printer is in Dispenser Mode this bit is never set.
Trig blocking
Trig block timer is active.
Printer alarm

Print head open, paper out, or ribbon out.

New in version Unreleased.

Soft inhibition
A software inhibition is active.
Applicator is active
Applicator is blocking printouts.

RD_MESSAGES_ALARMS

Description Address Offset
Read currently active alarms 30020 0x13
Value Description
0b0000000000000001 (1) low_air_pressure_alarm
0b0000000000000010 (2) paper_out
0b0000000000000100 (4) ribbon_out
0b0000000000001000 (8) printhead_open
0b0000000000010000 (16) applicator
0b0000000000100000 (32) product_failed
0b1000000000000000 (32768) any

Get active alarms. The lower bits are mapped to specific alarms or alarm groups. The highest bit (b15) is set whenever any alarm, including ones not represented by the lower bits, is active.

The description in the table below is the exact alarm name, as would have been reported as “message_id” in messages.active.changed , with the exception of b4 (which represents any alarm in the group “applicator”) and b15.


RD_MESSAGES_WARNINGS

Description Address Offset
Read currently active warnings 30021 0x14
Value Description
0b0000000000000001 (1) low_air_pressure_warning
0b0000000000000010 (2) paper_low
0b0000000000000100 (4) ribbon_low
0b0000000000010000 (16) applicator
0b1000000000000000 (32768) any

Get active warnings. The register works similar to RD_MESSAGES_ALARMS.


RD_JOB_STATE

Description Address Offset
Get job availability 30025 0x18
Value Description
0b0000000000000000 (0) No job
0b0000000000000001 (1) Job available
0b0000000000000011 (3) Ready to Print

Get job availability. API documentation: jobs.state.get


RD_STAND1_POS

Description Address Offset
Stand 1 position in mm 30031 0x1E
Value Description
0b0000011111111111 (2047) Position Mask
0b0000100000000000 (2048) Sign. 0 means positive. 1 means negative.
0b1000000000000000 (32768) Unknown Position

This register contains the last known position for the first motorized stand.

If b15 is 1 the position is unknown.

If b15 is 0, b10-b0 contains the stand position in mm in user coordinates.

b11 specifies the sign of the position value. 0 means positive, and 1 means negative.


RD_STAND2_POS

Description Address Offset
Stand 2 position in mm 30032 0x1F
Value Description
0b0000011111111111 (2047) Position Mask
0b0000100000000000 (2048) Sign. 0 means positive. 1 means negative.
0b1000000000000000 (32768) Unknown Position

This register contains the last known position for the second motorized stand.

For details, see RD_STAND1_POS.


RD_STAND3_POS

Description Address Offset
Stand 3 position in mm 30033 0x20
Value Description
0b0000011111111111 (2047) Position Mask
0b0000100000000000 (2048) Sign. 0 means positive. 1 means negative.
0b1000000000000000 (32768) Unknown Position

This register contains the last known position for the third motorized stand.

For details, see RD_STAND1_POS.


RD_SCANNER1_RESULT

Warning

Implementation is in beta state.

Description Address Offset
Scanner 1 read data (32 registers, 64 ASCII characters) 30041 0x28 - 0x47

These registers contain the scanner data from scanner 1.

Each register (16 bits) is interpreted as two ASCII characters. The data is truncated if it is longer that 64 characters. If shorter it is padded with 0x00. If the last status from the scanner is not "ok", the data will be the empty string (all 0x00).


RD_SCANNER2_RESULT

Warning

Implementation is in beta state.

Description Address Offset
Scanner 2 read data (32 registers, 64 ASCII characters) 30081 0x50 - 0x6F

These registers contain the scanner data from scanner 2.

For details, see RD_SCANNER1_RESULT.


RD_SCANNER3_RESULT

Warning

Implementation is in beta state.

Description Address Offset
Scanner 3 read data (32 registers, 64 ASCII characters) 30121 0x78 - 0x97

These registers contain the scanner data from scanner 3.

For details, see RD_SCANNER1_RESULT.

Holding Registers

Complex commands with parameters or options are issued by writing a 16 bit value to the corresponding address.


WR_MARKER_STATE

Description Address Offset
Set the printer online or offline 40001 0x00
Value Description
0b0000000000000000 (0) Offline
0b0000000000000001 (1) Online

Instruct the printer to go either offline or online.


WR_API_HEARTBEAT_TIMEOUT

Description Address Offset
Require WR_API_HEARTBEAT 40002 0x01

If client writes any value but 0 to this register, WR_API_HEARTBEAT must be written to at least every N seconds, where N is the value written to this register. If the client disconnects or WR_API_HEARTBEAT is not written to at least every N seconds, the printer will enter alarm state.

Set to 0 (default) to toggle off. Maximum accepted value is 10.

This setting is transient. If the client disconnects, or fails to send WR_ALIVE in time so that an alarm is raised, the value is reset to 0 and will have to be set again.

If any non 0 value has been written, a client must write 0 to this register again before disconnecting to avoid raising an alarm.


WR_API_HEARTBEAT

Description Address Offset
Ensure printer that Modbus client is alive 40003 0x02

Inform printer that the client is still alive. This is needed when WR_API_HEARTBEAT_TIMEOUT has been set to anything but 0.


WR_SEQUENCE_PRINT

Description Address Offset
Print active job immediately 40005 0x04
Value Description
0b0000000000000000 (0) Print
0b0000000000000001 (1) Print and Apply sequence 1
0b0000000000000010 (2) Print and Apply sequence 2
0b0000000000000011 (3) Print and Apply sequence 3

Print the active job immediately. API documentation: sequence.print

If the printer is not configured for External Sequence Control, only the value 0 may be written to this register. This will trigger printing of the loaded label.

If the printer is configured for External Sequence Control, the values 1, 2 or 3 written to this register will trigger both printing and then applying with the specified preconfigured External Apply Sequence, similar to if WR_SEQUENCE_APPLY had been written to when printing was completed. It is still possible to write 0 in this mode, in order to just trigger printing.


WR_SEQUENCE_APPLY

Description Address Offset
Apply label with specified apply sequence 40006 0x05
Value Description
0b0000000000000000 (0) Apply
0b0000000000000001 (1) Apply sequence 1
0b0000000000000010 (2) Apply sequence 2
0b0000000000000011 (3) Apply sequence 3

Apply current label. API documentation: sequence.apply

If the printer is not configured for External Sequence Control, only the value 0 may be written to this register, and initiates the apply sequence configured for the current label.

This is equivalent to invoking sequence.apply with no parameters.

If the printer is configured for External Sequence Control, only the values 1, 2 or 3 may be written to this register, and will then trigger the corresponding preconfigured External Apply Sequence.

Writing 1 is equivalent to invoking sequence.apply with the parameters {"index": 1}.


WR_SEQUENCE_ABORT

Description Address Offset
Abort the current product sequence 40007 0x06

Abort the current sequence. API documentation: sequence.abort


WR_SEQUENCE_FINISH

Description Address Offset
Indicate that current product sequence is finished 40008 0x07

Finish the current external sequence. Only applicable for External Sequence Control.

API documentation: sequence.finish

WR_MESSAGES_RESET

Description Address Offset
Reset active alarms 40020 0x13

Reset active alarms.

Note that not all alarms can be reset this way. Only alarms that would be possible to reset by pressing the Control Bar button Reset are possible to reset.


WR_JOB_CLEAR

Description Address Offset
Clear all jobs 40025 0x18

Remove all elements in the print job queue. API documentation: jobs.clear.


WR_STAND_STOP

Description Address Offset
Stop specified stands 40030 0x1D
Value Description
0b0000000000000001 (1) Stop Stand1
0b0000000000000010 (2) Stop Stand2
0b0000000000000100 (4) Stop Stand3

Stop specified stands. More than one stand can be specified. API documentation: stand.stop.


WR_STAND1_GOTO_MM

Description Address Offset
Goto stand position in mm 40031 0x1E
Value Description
0b0000011111111111 (2047) Position Mask
0b0000100000000000 (2048) Sign. 0 means positive. 1 means negative.

Move motorized stand to specified position in user coordinates.

In order to ensure that stands are moved only when there is a working communication, it is recommended to enable WR_API_HEARTBEAT_TIMEOUT before writing to this register.


WR_STAND2_GOTO_MM

Description Address Offset
Goto stand position in mm 40032 0x1F
Value Description
0b0000011111111111 (2047) Position Mask
0b0000100000000000 (2048) Sign. 0 means positive. 1 means negative.

Move stand2 to specified position. For details, see WR_STAND1_GOTO.


WR_STAND3_GOTO_MM

Description Address Offset
Goto stand position in mm 40033 0x20
Value Description
0b0000011111111111 (2047) Position Mask
0b0000100000000000 (2048) Sign. 0 means positive. 1 means negative.

Move stand3 to specified position. For details, see WR_STAND1_GOTO.


WR_STAND1_GOTO_STORED_POS

Description Address Offset
Goto stored position 40034 0x21

Move motorized stand to position with numerical name matching value written to this register. If you write e.g. 0x0002 to this registry there should be a configured position named "2" for the stand to go to.

In order to ensure that stands are moved only when there is a working communication, it is recommended to enable WR_API_HEARTBEAT_TIMEOUT before writing to this register.


WR_STAND2_GOTO_STORED_POS

Description Address Offset
Goto stored position 40035 0x22

Move stand2 to position with numerical name matching value written to this register

See WR_STAND1_GOTO_STORED_POS for details.


WR_STAND3_GOTO_STORED_POS

Description Address Offset
Goto stored position 40036 0x23

Move stand3 to position with numerical name matching value written to this register

See WR_STAND1_GOTO_STORED_POS for details.

See Also

More information about Modbus and Modbus TCP can be found at http://www.modbus.org