# GSI Aurora
> Protocol and API documentation for GSI Aurora: REST API, Aurora API, JSON objects, dynamic text, and color specification.
This file contains all documentation content in a single document following the llmstxt.org standard.
## Protocol specification
:::info
The protocol is available on TCP/IP port `10001`.
:::
The protocol is **line-based**, meaning each request and each response
is transmitted as a **single line of text**.
All requests are executed in order, and each request generates exactly
one response. After sending a request, it is important to read the
entire response. Otherwise, the TCP/IP connection will stall when the
transmit buffer in the printer is full. Alternatively, responses can
be suppressed by prefixing the request with a tile character.
## Line termination
A line may be terminated using any of the following:
- **LF** — ASCII line feed, decimal `10`, hex `0A`
- **CR** — ASCII carrige return, decimal `13`, hex `0D`
- **CR+LF**
## Character encoding
All content must be encoded using **UTF-8**.
## Request format
The format of the request is a method name, followed by an optional
parameter as a JSON value, separated by a single space.
If a client does not need to know whether a request is successful or
not, the request can be prefixed with a tilde character (`~`),
e.g. "`~trigger`". This will cause the printer to omit sending a
response, and instead terminate the connection on error.
## Reponse format
The format of a response is a single line consisting of a status code
followed by a single space and a JSON variable. The status code is one
of the following:
| Status code | Description |
| ------------------ | --------------------------------------------------------------------------------------------------------------- |
| `OK` | The request was successful. |
| `METHOD_NOT_FOUND` | The requested method does not exist. |
| `INVALID_PARAMS` | The parameters are invalid, e.g. it could be invalid JSON, the wrong type, or be missing required keys. |
| `REQUEST_FAILED` | The request failed, e.g. a request for an object that doesn't exist, or the printer is in the wrong state, etc. |
The returned variable can be of any valid JSON type, e.g. `null`, a
string, an object, etc. For successful requests (with status `OK`),
the type of the response depends on the request. For unsuccessful
requests, the type is always a string.
Responses that do not have a meaningful return value will still return
`null`. For example:
```json
OK null
```
---
## Introduction
:::danger Deprecated
This protocol/API is deprecated and should not be used.
:::
## Overview
This API is comliant with the JSON-RPC 2.0 specification. More information available at [http://www.jsonrpc.org/specification](https://www.jsonrpc.org/specification).
The protocol is available on TCP/IP port 10001.
**This protocol is deprecated and should not be used.**
## Authentication
TBD
## Errors
TBD
---
## Introduction(Docs)
:::note
This documentation is updated for GSI Aurora software v5.0.
:::
:::tip[Using AI agents?]
This documentation is available in Markdown for LLMs and AI coding agents:
[`/llms.txt`](pathname:///llms.txt) (a curated index) and
[`/llms-full.txt`](pathname:///llms-full.txt) (the full documentation in one
file). Any page is also available as raw Markdown by appending `.md` to its URL.
:::
## Color
GSI Aurora provides comprehensive support for defining colors across all label objects, allowing for advanced customization and flexibility. The Web UI features a user-friendly color selection tool that makes it easy for users to pick and apply colors as needed. For those who wish to define colors manually or require more in-depth customization, detailed guidelines and specifications on how to accurately define and format colors are documented thoroughly here:
- [Color specification](./color)
## Dynamic text
GSI Aurora offers robust support for advanced dynamic text capabilities, enabling users to incorporate elements such as variables, date/time stamps, counters, and more. These dynamic text features can be utilized through an intuitive, easy-to-learn language designed to simplify the process of creating complex text behaviors. To help users make the most of this functionality, the dynamic text language is thoroughly documented with numerous examples and use cases provided here:
- [Dynamic text](./dynamic-text)
## Protocol (API)
GSI Aurora can be accessed remotely, or from extensions, using two different protocols: REST and Aurora-API. Note that in some situations it makes more sense to call these protocol APIs.
The REST (Representational State Transfer) API is a popular architectural style for building web services. It provides a set of conventions and best practices that make it easier for developers to build, use, and maintain web-based systems. Although REST APIs are designed to be straightforward, using them still involves a lot of repetitive tasks, like setting up requests, handling responses, and working with data. A client library helps simplify all these tasks by taking care of the technical details, making it much easier and faster to use the API.
The other API is the Aurora API, a text-based protocol designed for ease of use, especially when working with devices that lack an HTTP client library. Due to its minimal overhead, the Aurora API offers significantly faster performance. Additionally, several low-level requests are exclusively accessible through the Aurora API.
Both protocols are documented here:
- [REST API](./rest-api/intro)
- [Aurora API](./aurora-api/intro) (new in v3.1.0)
Both of these protocols use JSON extensively for data exchange. Since the JSON objects are shared between the REST and Aurora API, they are documented separately here:
- [JSON Objects](./json-objects/intro)
## Legacy documentation
The following protocols are deprecated, and should not be used for new projects:
- [JSON-RPC API](./deprecated/json-rpc/intro) (deprecated)
---
## Introduction(Json-objects)
The JSON objects documented in this section are shared betwee multiple
protocols and API:s.
---
## Introduction(Label)
:::info
The unit of all coordinates, lengths, and sizes are in millimeters.
:::
A label is a JSON object with the following mandatory properties:
| Property | Type | Description |
|----------|--------------------------------------|---------------------------------------------------------------------------------------|
| format | number | The format of labels conforming the this specification must be `3`. |
| width | number | Width of the label. A width of zero means that it will be automatically calculated. |
| height | number | Height of the label. A height of zero means that it will be automatically calculated. |
| objs | array of [label objects](./objects/) | See below for description. |
The following optional properties are also available:
| Property | Type | Description |
|----------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| bgColor | string | Label background color. |
| printDelay | number | Print delay override in millimeters. |
| margin | number | Deprecated. Use `printDelay` instead. |
| hdpi | number | Horizontal resolition setting override (in dots per inch). |
| vdpi | number | Vertical resolition setting override (in dots per inch). |
| vOffset | number | Vertical offset setting override. A positive value moves the label up. |
| rotation | number | Rotation settings override. If set, must be one of `NONE`, `CW90` for 90° clockwise rotation, `CW180` for 180° rotation, or `CCW90` for 90° counterclockwise rotation. |
| stretch | number | Stretch setting override, where a value of 1 means no stretch. |
:::info Example
```json
{
"format": 3,
"width": 50.0,
"height": 108.37,
"objs": [
{
"type": "Rect",
"x": 10.0,
"y": 10.0,
"height": 20.0,
"width": 20.0,
"fillColor": "black"
}
]
}
```
:::
---
## Introduction(Rest-api)
The API is organized around REST. Our API has predictable resource-oriented URLs, and uses standard HTTP request verbs (GET, PUT, POST, DELETE). Most methods accept JSON-encoded request bodies and return JSON-encoded responses.
All URLs start with `/api/{version}/` where `{version}` is currently v3, i.e. `/api/v3/`.
## Authentication
TBD
## Error handling
GSI uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with the printer (these are rare).
## Python client
Python is very useful to use and test the REST API because it has built-in support for both HTTP and JSON.
The following example will read and print the printer status:
```python
rsp = requests.get('http://192.168.1.1/api/v3/status')
print(json.loads(rsp.content.decode()))
```
The following example selects a print job from the table "My Table":
```python
rsp = requests.post(
url = 'http://192.168.1.1/api/v3/printJob',
headers = {'Content-Type': 'application/json'},
data = json.dumps(
{
'tableName': 'My Table',
'keyColumn': 'SKU',
'key': 'S12-342C',
'labelColumn': 'Label',
'labelName': 'MEDIUM',
'queue': True,
}))
```
---
## Color
Color is specified as a string. There are several methods to specify colors.
### Named color
The following common colors are available: `black`, `white`, `gray`, `red`, `green`, `blue`, `cyan`, `magenta`, `yellow`. All standard web colors are also available.
See [https://en.wikipedia.org/wiki/Web\_colors](https://en.wikipedia.org/wiki/Web_colors) for a complete list.
### RGB color
Specify color as sRGB, e.g. `rgb(20%, 0%, 80%)` for 20% red, 0% green and 80% red. Color management will be used for CMYK printers with an active color profile.
### CMYK color
Specify color as CMYK, e.g. `cmyk(70%, 10%, 80%, 10%)` for 70% cyan, 10% magenta, 80% yellow and 10% black. Not color managed. Smart white will be applied when using on a Colorize CMYK+W.
### Single ink color
* `magenta(50%)` where "magenta" is the color name of any of the ink color.
### Direct ink mix
* `ink(c1, c2, …, cN)` where N is the number of inks. Two color printer example: `ink(25%,50%)`
### Special colors
There are two special color codes:
| Code | Description |
| ------- | ---------------------------------------------------------- |
| `none` | The object will be invisible. |
| `blank` | The object will be painted with blank space (i.e. no ink). |
---
## Counters
The code to insert a counter is `{COUNTER}`. It requires at least one parameter, which is the name of the counter to insert.
Example:
> S/N: `{COUNTER;SerialNum}`
Assuming the variable `SerialNum` has the value 42, and a width of 4 characters, then it will be printed like this:
> S/N: 0042
Additional [number formatting parameters](./number-formatting) can be added to control how the counter is formatted, e.g. the width and padding character can be changed.
> Batch: `{COUNTER;SerialNum;WIDTH=5;PADDING=#}`
This will instead be printed as:
> S/N: ###42
See the [Number formatting](./number-formatting) section for more advanced examples.
---
## Database tables
## TABLE
The code to insert a value for a database table is `{TABLE}`. It requires at least one parameter, which is the name of the column from which to pick the value. As an alternative, the argument may be an integer, which is a zero-based column index. In general it is recommended to use the name of the column and not the index.
Example:
> Product: `{TABLE;Description}`
Assuming the table has a column "Description", which on the current row has the value "Bananas", the following would be printed:
> Product: Bananas
## XTABLE
The `{XTABLE}` code performs a key-based lookup in a table — searching for a row where a specified column matches a given key, and returning the value from another column. Unlike `{TABLE}`, which reads from the current row in the active print job environment, `{XTABLE}` can query any named table regardless of context.
All parameters are required except `fallback`. If no matching row is found and no fallback is provided, an error is raised.
| Parameter | Type | Description |
|-----------|--------|-------------|
| `tableName` | string | Name of the table to query. |
| `keyColumn` | string | Column name to search in. |
| `key` | string | Value to search for in `keyColumn`. Supports dynamic text. |
| `valueColumn` | string | Column name whose value to return. |
| `fallback` | string | Value to use if no matching row is found. Supports dynamic text. |
Example:
> Country: `{XTABLE;Countries;Code;{VARIABLE;country_code};Name}`
This looks up the row in table "Countries" where column "Code" matches the value of variable `country_code`, and prints the corresponding "Name" column value.
With a fallback:
> Country: `{XTABLE;Countries;Code;{VARIABLE;country_code};Name;Unknown}`
If no matching row is found, "Unknown" is printed instead of raising an error.
---
## Clocks
By default, the `{TIME}` code uses the current time. A custom clock can be used instead, so that the printed date and time is taken from a value set by an operator rather than from the printer's own clock.
A custom clock is a named, fixed date and time value. Clocks are created using the Web UI or the [Clocks API](/docs/aurora-api/methods/Clocks/setClocks). A typical use case is a production date that is set once and then used by one or more labels. A clock can be marked as user editable, in which case the operator is asked to confirm or change its value when selecting a label that uses it.
## Syntax
The clock name is given as the fourth argument of the `{TIME}` code:
> `{TIME;format;offset;clock}`
Both the offset and the clock are optional. To use a clock without an offset, leave the offset argument empty but keep its semicolon:
> `{TIME;@YYYY-MM-DD;;PRODDATE}`
If an offset is given, it is applied to the clock's date and time instead of the current time. This makes it easy to print derived dates, such as a best before date calculated from a production date.
Referencing a clock that does not exist is an error, and the label will fail to print.
## Examples
The examples below assume a clock named `PRODDATE` set to 16 May 2026.
* `{TIME;@YYYY-MM-DD;;PRODDATE}`\
The clock value using a predefined format: "2026-05-16".
* `{TIME;@DD/MM/YY;;PRODDATE}`\
The same clock with another format: "16/05/26".
* `{TIME;@YYYY-MM-DD;+6months;PRODDATE}`\
A best before date six months after the production date: "2026-11-16".
* `{TIME;@YYYY-MM-DD;+1year-1day;PRODDATE}`\
One year minus one day after the production date: "2027-05-15".
* `{TIME;{DAYOFMONTH} {MONTH;FORMAT=shortmonth} {YEAR};;PRODDATE}`\
Individual [components](components) formatted from the clock: "16 MAY 2026".
* `{TIME;{WEEK};;PRODDATE}`\
The week number of the production date: "20".
* `{TIME;@YYYY-MM-DD;+{VARIABLE;SHELF_LIFE}days;PRODDATE}`\
A best before date where the shelf life in days is taken from the variable `SHELF_LIFE`.
Note that components like `{DAYOFMONTH}` only use the clock when placed inside a `{TIME}` code that selects it. A standalone `{DAYOFMONTH}` always uses the current time.
---
## Components
The following date components are available:
| Component | Description |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `{AMPM}` | 1 for AM and 2 for PM. Typically used with format like this:`{AMPM;FORMAT={AM;PM}}``{AMPM;FORMAT={ a.m.; p.m.}}` |
| `{DAYOFMONTH}` | Day of month (1-31) |
| `{DAYOFWEEK}` | Day of week beginning with Monday (1-7) |
| `{DAYOFWEEK_US}` | Day of week beginning with Sunday (1-7) |
| `{DAYOFYEAR}` | Day of year (1-366) |
| `{HOUR}` | Hour of the day (0-23) |
| `{HOUR12}` | Hour of day using 12-hour time (0-12) |
| `{ISOWEEK}` | ISO-8601 year number. |
| `{ISOYEAR}` | ISO-8601 year. |
| `{MINUTE}` | Minute of hour (0-59) |
| `{MONTH}` | Month number (1-12) |
| `{SECOND}` | Second of hour (0-60) |
| `{YEAR}` | Current year, e.g. “2021”. |
| `{YEAROFMILLENIUM}` | Year of the current century, e.g. “023” for 2023. |
| `{YEAROFCENTURY}` | Year of the current century, e.g. “23” for 2023. |
| `{YEAROFDECADE}` | Year of the current decade, e.g. “3” for 2023. |
| `{WEEK}` | Week number |
| `{WEEK_US}` | US week number |
---
## Examples
All examples on this page assume that the current time is Sunday 28 August 2022, 21:45:30.
## Predefined formats
* `{TIME;@YYYY-MM-DD}`\
"2022-08-28"
* `{TIME;@DD/MM/YY}`\
"28/08/22"
## Individual components
* `{DAYOFMONTH}/{MONTH}/{YEAROFCENTURY}`\
"28/08/22" — the same result as `{TIME;@DD/MM/YY}` above, built from components.
* `{HOUR}:{MINUTE}`\
"21:45" — components are zero-padded to their natural width by default.
* `{YEAR} week {WEEK}`\
"2022 week 34"
* `{TIME;{HOUR12}:{MINUTE}{AMPM}}`\
"09:45PM" — 12-hour time with an AM/PM suffix.
* `{TIME;{HOUR12}:{MINUTE}{AMPM;FORMAT={ a.m.; p.m.}}}`\
"09:45 p.m." — the same, but with custom AM/PM texts.
## Custom number formats
* `{MONTH;FORMAT=shortmonth}`\
"AUG" — the built-in `shortmonth` format prints month names.
* `{TIME;{MONTH;FORMAT={A;B;C;D;E;F;G;H;J;K;L;M}}}`\
"H" — the month picked from a custom list, A for January through M for December (skipping I). August is the eighth entry.
## Offsets
* `{TIME;@YYYY-MM-DD;+20days}`\
"2022-09-17" — a best before date 20 days from now.
* `{TIME;@YYYY-MM-DD;+3months-1week}`\
"2022-11-21" — offset terms can be combined.
* `{TIME;{MONTH;FORMAT=shortmonth};+6weeks}`\
"OCT" — the month name six weeks from now.
* `{TIME;{YEAR}{DAYOFYEAR};+1month}`\
"2022271" — the Julian date one month from now.
* `{TIME;@YYYY-MM-DD;+{VARIABLE;SHELF_LIFE}days}`\
A best before date where the number of days is taken from the variable `SHELF_LIFE`. If the variable is "14", the result is "2022-09-11".
## Clocks
These examples use a [custom clock](clocks) named `PRODDATE` set to 16 May 2022.
* `{TIME;@YYYY-MM-DD;;PRODDATE}`\
"2022-05-16" — the clock value instead of the current time. Note the empty offset argument.
* `{TIME;@YYYY-MM-DD;+6months;PRODDATE}`\
"2022-11-16" — a best before date six months after the production date.
---
## Date and time
The date and time dynamic text codes are by far the most advanced and powerful codes. They are easy to use in their basic form, but have a lot of flexibility to add offsets and control the formatting of the numbers.
There are two main options when using date/time codes: predefined composite formats, or individual components like the year, month, hour, etc.
To use predefined formats, the `{TIME}` code is used with the name of the format as parameter (prefixed by a "@" character), e.g. `{TIME;@YYYY-MM-DD}`.
The individual components can either be placed inside a `{TIME}` code as in `{TIME;{HOUR}}`, or standalone as in `{HOUR}`. The advantage of placing the components inside a `{TIME}` code is mainly to apply an offset to create best before dates, or to use a custom clock instead of the current time.
> Best before: `{TIME;@YYYY-MM-DD;+20days}`
The built-in format `YYYY-MM-DD` is just a short form for `{YEAR}-{MONTH}-{DAYOFMONTH}`, so the following dynamic text is equivalent:
> Best before: `{TIME;{YEAR}-{MONTH}-{DAYOFMONTH};+20days}`
---
## Offsets
The TIME dynamic text code allows for a time offset to be applied to time and date dynamic text codes. The first argument is any dynamic text, and the (optional) third argument applies an offset to the current time. The offset is expressed as an arithmetic expression (only plus and minus is supported) that can also use the following dynamic components (expressed without braces):
* year
* month
* week
* day
* hour
* minute
Plural versions are also accepted, e.g. years, months, weeks, days, hours, minutes. Standard dynamic text codes can be used in the offset. Examples:
* `{TIME;{YEAR}{DAYOFYEAR};+1month}`
* `{TIME;{YEAR}{DAYOFYEAR};+3months-1week-4hours}`
* `{TIME;{YEAR}{DAYOFYEAR};+{VARIABLE;WEEK_OFFSET}weeks}`\
(If the variable `WEEK_OFFSET` has the value “4”, then this is equivalent to +4weeks.
---
## Predefined formats
The printer has a number of predefined formats to make it more convenient to insert common date and time formats. Custom formats can also be added using the Web UI or protocols.
To use a predefined date/time format, the `{TIME}` code is used with the name of the format as the first parameter, prefixed by a "@" character. For example:
> Today is `{TIME;@YYYY-MM-DD}`, in 20 days it's `{TIME;@YYYY-MM-DD;+20days}`
The following formats are built in:
| Format | Example |
| ---------- | ---------- |
| DD/MM/YYYY | 28/08/2022 |
| DD/MM/YY | 28/08/22 |
| DD MM YYYY | 28 08 2022 |
| DD MM YY | 28 08 22 |
| DD.MM.YYYY | 28.08.2022 |
| DD.MM.YY | 28.08.22 |
| MM/DD/YYYY | 08/28/2022 |
| MM/DD/YY | 08/28/22 |
| YYYY-MM-DD | 2022-08-28 |
| YY-MM-DD | 22-08-28 |
---
## Dynamic text
Dynamic text is a feature in the printer that allows text to change dynamically when printed. All label objects that uses text as content can take advantage of the dynamic text feature of the printer. The most obvious examples are text and bar codes, but dynamic text can also be used to control the name of an image file, or event the color of objects.
A dynamic text is a mix of regular text and dynamic text codes. Each dynamic text code represents a text that changes its value based on the circumstances when printing, e.g. the current time and date, or how many labels have been printed, or which database table row is active.
All dynamic text codes are encoded in curly braces, e.g. `{YEAR}`. When printed, this code will be replaced by the current year, e.g. 2024. It is common to mix regular text and dynamic text codes:
> The current month is `{MONTH}`, and the year is `{YEAR}`.
If printed in October 2024, it will be printed as the following:
> The current month is 10, and the year is 2024.
Many dynamic text objects take one or more parameters, which are separated by semicolons. For example, the dynamic text `{VARIABLE;MyVariable}`, which will be replaced by the current value of the variable `MyVariable`.
Some dynamic text codes can even be nested. The most common example is the `{TIME}` code which is used to shift the time to implement features like best before dates.
> Best before: `{TIME;{YEAR}-{MONTH}-{DAYOFMONTH};+20weeks}`
If printed on October 4, 2024, it will be printing as:
> Best before: 2024-02-21
---
## Number formatting
## Padding
Padding is controlled by adding a parameter that begins with either `WIDTH=` (to control the minimum number of digits), and/or `PADDING=` which changes the default padding character from zero to some other character, e.g. space. For example:
| Number | Parameter | Result |
| ------ | ------------------- | ------ |
| 42 | _(none)_ | 42 |
| 42 | `WIDTH=5` | 00042 |
| 42 | `WIDTH=5;PADDING=␣` | ␣␣␣42 |
## Number to text conversion
The format used to convert a number to a text can be changed by adding a parameter that starts with `FORMAT=`. The following formats are built in, but more formats can be created by the user:
Format
Description
alpha
Alpha encoding using capital letters. Exactly the same as #ABCDEFGHIJKLMNOPQRSTUVWXYZ
shortmonth
Translates numbers 1-12 into an English three capital letter month name.(JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC)
shortweekday
Translates numbers 1-12 into an English three capital letter week day name.(MON, TUE, WED, THU, FRI, SAT, SUN)
y
Additionally, the following special formats are available, determined by the special first character of the format:
First character
Format
Description
`{`
`{word1,word2,...}`
Use a lookup table. The words are separated by semicolon (;), plus a closing brace at the end. For example:
`FORMAT={ONE;TWO}`
This will convert the number 1 to the text `ONE`, and 2 to `TWO`. Any other number will generate an error.
If the first word starts with `#`, then it changes the starting number from 1 to something else, which can be very useful when converting years to special texts, like this:
`{YEAR;FORMAT={#2020;A;B;C;D;E}}`If the year is 2022, `C` will be printed.
`#`
`#numerals`
Use numerals instead of standard numerals 0-9. For example:
`#01234567890ABCDEF`
(Hexadecimal)
`#ABCDEFGHIJKLMNOPQRSTUVWXYZ`
(Letters A-Z)`#ABCDEFGHJKLMNPQRSTUVWXYZ`
(Letters A-Z except I or O)
---
## Shift codes
The code to insert a shift code is `{SHIFTCODE}`. It requires at least one parameter, which is the name of the shift code to insert.
Example:
> Shift: `{SHIFTCODE;MyShift}`
Assuming the variable `MyShift` has the value `A` at the current time, it will be printed like this:
> Shift: A
The time used to resolve a shift code can me modified by placing it inside a `{TIME}` code. For example, to use the time two hours ago instead of the current time:
> Shift: `{TIME;{SHIFTCODE;MyShift};-2hours}`
---
## Special characters
## ASCII
The following ASCII codes are recognized:
`{NUL}`, `{SOH}`, `{STX}`, `{ETX}`, `{EOT}`, `{ENQ}`, `{ACK}`, `{BEL}`, `{BS}`, `{HT}`, `{LF}`, `{VT}`, `{FF}`, `{CR}`, `{SO}`, `{SI}`, `{DLE}`, `{DC1}`, `{DC2}`, `{DC3}`, `{DC4}`, `{NAK}`, `{SYN}`, `{ETB}`, `{CAN}`, `{EM}`, `{SUB}`, `{ESC}`, `{FS}`, `{GS}`, `{RS}`, `{US}`
In addition to these, `{TAB}` can be used as an alias for `{HT}`.
## Unicode
Unicode characters can be inserted using `{U+nnnn}` where nnnn is the hexadecimal Unicode, e.g. `{U+20AC}` for the Euro symbol (€), or `{U+1B}` which is equivalent to `{ESC}`.
## Non-breaking space
The code `{NBSP}` is used to insert a non-breaking space, i.e. a space that is not used to break lines.
---
## Special codes
## Voice pick codes
Voice pick codes can be constructed using the `{VOICEPICKCODE}` code. It takes two mandatory arguments: the GTIN, the lot number, as well as an optional date code and settings. By default, the code will generate text containing advanced formatting code to increase size of the large digits.
:::info
For the text to be formatted correctly, the text object must have the text formatting set to ADVANCED.
:::
The optional fourth parameter can be set to `S` to only generate the two small digits, `L` to only generate the two large digits, or `SL` to generate all four digits, without advanced text formatting codes.
### Examples
If the GTIN is 10850510002011, the lot code is 46587443HG234, and no date code is desired:
> `{VOICEPICKCODE;10850510002011;46587443HG234}`
To include the date in the voice pick code, another argument is required, e.g. using the built-in date format `YYMMDD`:
> `{VOICEPICKCODE;10850510002011;46587443HG234;{TIME;@YYMMDD}}`
To generate only the two small digits (63 in this case):
> `{VOICEPICKCODE;10850510002011;46587443HG234;;S}`
The following example will result in the text "59":
> `{VOICEPICKCODE;10850510002011;46587443HG234;;L}`
The three first arguments can be dynamic texts themselves, e.g. from a database table. Assuming that the table has a column GTIN, and and another column LOT, then the code will look like this:
> `{VOICEPICKCODE;{TABLE;GTIN};{TABLE;LOT};{TIME;@YYMMDD}}`
## Random number
Random numbers can be generated using the `{RANDOM}` code, which takes the minimum and maximum values as two arguments:
> `{RANDOM;100;999}`
---
## Utilities
## Sub-string extraction
The `{SUBSTR}` code is used to extract a sub-string from a text. The first parameter is the text to process, the next is a (zero based) index of the first character to extract, and the optional third parameter is the number of characters to extract. If the number of characters is not specified, all characters until the end of the text will be extracted.
For the following examples, assume that the variable `MyVariable` contains the value `ABCDEFGH`:, and that the current year is 2024:
```
{SUBSTR;{VARIABLE;MyVariable};3} -> DEFGH
{SUBSTR;{VARIABLE;MyVariable};3,1} -> D
{SUBSTR;{VARIABLE;MyVariable};0,2} -> AB
{SUBSTR;{YEAR};3;1} -> 4
```
---
## Variables
The code to insert a variable is `{VARIABLE}`. It takes a single parameter, which is the name of the variable to insert.
Example:
> Batch: `{VARIABLE;BATCH_NO}`
Assuming the variable `BATCH_NO` has the value `B007`, then it will be printed like this:
> Batch: B007
---
## Clock
## Mandatory properties
| Property | Type | Description |
| -------- | ------ | ------------------------------- |
| dateTime | object | A [DateTime](#datetime) object. |
## Optional properties
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------------------------------ |
| pinned | boolean | If true, the clock is pinned in the UI. Default is `false`. |
| userEdit | boolean | If true, the clock shall be changeable when an operator selects a label that uses it. Default is `false`. |
## DateTime
A JSON object representing a date and time.
### Mandatory properties
| Property | Type | Description |
| -------- | ------- | --------------------- |
| year | integer | Year, e.g. `2026`. |
### Optional properties
| Property | Type | Description |
| -------- | ------- | -------------------------------------- |
| month | integer | Month, 1-12. Default is `1`. |
| day | integer | Day of month, 1-31. Default is `1`. |
| hour | integer | Hour, 0-23. Default is `0`. |
| minute | integer | Minute, 0-59. Default is `0`. |
| second | integer | Second, 0-60. Default is `0`. |
## Example
```json
{
"dateTime": {
"year": 2026,
"month": 5,
"day": 16,
"hour": 12,
"minute": 0,
"second": 0
},
"pinned": false,
"userEdit": true
}
```
---
## Counter
## Mandatory properties
| Property | Type | Description |
| -------- | ------- | ------------------------------------------------------------------------- |
| maxValue | integer | The maximum value that `value` can have. |
| minValue | integer | The minimum value that `value` can have. |
| repeat | integer | The number of ticks before `value` is increased (or decreased) by `step.` |
| value | integer | The current value. |
| width | integer | The minimum number of digits in the resulting text. |
## Optional properties
| Property | Type | Description |
| -------- | ------- | --------------------------------------------------------------------------------------------------- |
| format | string | A [number format](../dynamic-text/number-formatting) used to convert the numeric `value` to a text. |
| padding | string | A single padding character. The character is used to pad the text up to `width` number of digits. |
| step | integer | The number to increase (or decrease) `value` by. Can be negative. |
## Example
```json
{
"maxValue": 99,
"minValue": 0,
"repeat": 0,
"step": 1,
"value": 0,
"width": 2
}
```
---
## Distance
A distance value can be given either as a plain number or as a string with a unit suffix.
When given as a plain number, the value is interpreted in the unit documented for the specific field (for example millimeters or nanometers).
When given as a string, it consists of a number followed by a unit suffix, for example `"5 mm"`, `"1.5 cm"`, or `"0.5 in"`. The following units are supported:
| Unit | Suffixes |
|------------|-------------------|
| Meter | `m` |
| Centimeter | `cm` |
| Millimeter | `mm` |
| Micrometer | `um`, `µm` |
| Inch | `in`, `inch`, `"` |
| Foot | `ft`, `foot`, `feet`, `'` |
---
## Font
Supported font file formats are TrueType (.ttf) and and OpenType (.otf).
## Mandatory properties
| Property | Type | Description |
| -------- | ------ | --------------------------------- |
| data | string | Font data as Base64 encoded text. |
## Example
```json
{
"data": "AAEAAAAPA...IVkfwMAQ",
}
```
---
## Image
Supported image formats are NetPBM, PNG, JPEG and TIFF.
## Mandatory properties
| Property | Type | Description |
| -------- | ------ | ---------------------------------- |
| data | string | Image data as Base64 encoded text. |
## Optional properties
| Property | Type | Description |
| -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| intent | string | Image color handling. May be one of: `RAW`, `SPOT_COLOR`, `PERCEPTUAL`, `RELATIVE_COLORIMETRIC`, `SATURATION`, `ABSOLUTE_COLORIMETRIC`. |
## Example
```json
{
"data": "SUkqADgCAA...IAAgA",
"intent": "SPOT_COLOR"
}
```
---
## Import
## Optional properties
| Property | Type | Description |
| ----------- | ----- | -------------------------------------------- |
| counters | array | Array of [counter](./counter) objects. |
| fonts | array | Array of [font](./font) objects. |
| images | array | Array of [image](./image) objects. |
| labels | object | Object mapping label names to [label](./label) objects. |
| shiftcodes | array | Array of [shift code](./shift-code) objects. |
| tables | array | Array of [table](./table) objects. |
| timeformats | array | Array of [time format](./time-format) objects. |
| variables | array | Array of [variable](./variable) objects. |
## Example
```json
{
"labels": {
"My Label": {
"height": 768,
"width": 500,
"objs": [
{
"type": "Rect",
"x": 55,
"y": 38,
"height": 100,
"width": 100,
"fillColor": "black"
}
]
}
}
}
```
---
## Common barcode properties
The following properties are shared by all linear and stacked barcode types that inherit from `BarcodeBase`: [Code128](./code128), [GS1-128](./code128-gs1), [GS1-128-Plain](./code128-gs1-plain), [Code128-ZPL](./code128-zpl), [Code39](./code39), [EAN-13](./ean13), [EAN-8](./ean8), [UPC-A](./upc-a), [ITF](./itf), and [ITF-14](./itf14).
These types also inherit all [common label object properties](../common-properties).
## Mandatory properties
| Property | Type | Description |
|-----------|--------|------------------|
| barHeight | number | Bar height. |
## Optional properties
| Property | Type | Description |
|----------------|-------------------|----------------------------------------------------------------------------------------------------------------|
| barWidth | number | Width of the narrowest bar element. Default is `1`. |
| quietZone | boolean | Enable or disable the quiet zone. Default is `true`. |
| extraQuietZone | number | Extra quiet zone width added on all sides, in addition to the standard quiet zone. |
| debleed | number | Ink spread compensation. Reduces each bar width by this amount to counteract ink bleeding. |
| barColor | string | [Color](/docs/color) of the bars. May contain [dynamic text](/docs/dynamic-text). Default is `black`. |
| textColor | string | [Color](/docs/color) of the human-readable text below the barcode. Defaults to the value of `barColor`. |
| font | [Font](../../types/font) | Font for the human-readable text below the barcode. |
---
## GS1-128-Plain
GS1-128-Plain encodes GS1 data supplied as a plain text string using parenthesized Application Identifier (AI) notation, for example `(01)12345678901231(10)LOT001`.
## Mandatory properties
The following properties are available in addition to the [common label object properties](../common-properties) and [common barcode properties](./barcode-common-properties).
| Property | Type | Description |
|-----------|--------|--------------------------------------------------------------------------------|
| type | string | Must be `GS1-128-Plain`. |
| text | string | GS1 data string in parenthesized AI notation. May contain [dynamic text](../../../../dynamic-text). |
| barHeight | number | Bar height. |
## Optional properties
The following properties are available in addition to the [common barcode properties](./barcode-common-properties).
| Property | Type | Description |
|----------|---------|-----------------------------------------------------------------------|
| optimize | boolean | If true, optimizes the encoding by selecting the most compact subset. Default is `false`. |
## Example
```json
{
"type": "GS1-128-Plain",
"x": 10.0,
"y": 10.0,
"text": "(01)12345678901231(10)LOT001",
"barHeight": 15.0,
"barWidth": 0.3
}
```
---
## GS1-128
GS1-128 encodes structured GS1 data using Application Identifiers (AIs).
## Mandatory properties
The following properties are available in addition to the [common label object properties](../common-properties) and [common barcode properties](./barcode-common-properties).
| Property | Type | Description |
|-----------|--------|------------------------------------------|
| type | string | Must be `GS1-128`. |
| apps | array | Array of GS1 Application Identifier objects. Each entry has `id` (string) and `value` (string). |
| barHeight | number | Bar height. |
Each app in the `apps` array may be specified either as an object `{"id": "01", "value": "..."}` or as a two-element array `["01", "..."]`.
## Example
```json
{
"type": "GS1-128",
"x": 10.0,
"y": 10.0,
"barHeight": 15.0,
"barWidth": 0.3,
"apps": [
{"id": "01", "value": "12345678901231"},
{"id": "10", "value": "LOT001"}
]
}
```
---
## Code128-ZPL
Code128-ZPL encodes data using Code 128 with ZPL-compatible mode selection.
## Mandatory properties
The following properties are available in addition to the [common label object properties](../common-properties) and [common barcode properties](./barcode-common-properties).
| Property | Type | Description |
|-----------|--------|--------------------------------------------------------------------------------|
| type | string | Must be `Code128-ZPL`. |
| text | string | Barcode data. May contain [dynamic text](../../../../dynamic-text). |
| barHeight | number | Bar height. |
| mode | string | Encoding mode. Allowed values: `NORMAL`, `UCC_CASE`, `AUTO`, `UCC_EAN`. |
## Example
```json
{
"type": "Code128-ZPL",
"x": 10.0,
"y": 10.0,
"text": "ABC-12345",
"barHeight": 15.0,
"barWidth": 0.3,
"mode": "AUTO"
}
```
---
## Code128
## Mandatory properties
The following properties are available in addition to the [common label object properties](../common-properties) and [common barcode properties](./barcode-common-properties).
| Property | Type | Description |
|----------|--------|--------------------------------------------------------------------------|
| type | string | Must be `Code128`. |
| text | string | Barcode data. May contain [dynamic text](../../../../dynamic-text). |
| barHeight | number | Bar height. |
## Optional properties
The following properties are available in addition to the [common barcode properties](./barcode-common-properties).
| Property | Type | Description |
|----------|--------|----------------------------------------------------------------------------------------------------------|
| encoding | string | Encoding mode. Allowed values: `AUTO`, `A`, `B`, `C`. Default is `AUTO`. |
## Example
```json
{
"type": "Code128",
"x": 10.0,
"y": 10.0,
"text": "ABC-12345",
"barHeight": 15.0,
"barWidth": 0.3
}
```
---
## Code39
## Mandatory properties
The following properties are available in addition to the [common label object properties](../common-properties) and [common barcode properties](./barcode-common-properties).
| Property | Type | Description |
|-----------|--------|------------------------------------------------------------------|
| type | string | Must be `Code39`. |
| text | string | Barcode data. May contain [dynamic text](../../../../dynamic-text). |
| barHeight | number | Bar height. |
## Optional properties
The following properties are available in addition to the [common barcode properties](./barcode-common-properties).
| Property | Type | Description |
|------------|---------|-------------------------------------------------------------------------|
| barRatio | number | Ratio of the wide bar to the narrow bar width. Default is `2.5`. |
| checkDigit | boolean | If true, appends a Mod-43 check digit to the encoded data. Default is `false`. |
## Example
```json
{
"type": "Code39",
"x": 10.0,
"y": 10.0,
"text": "ABC-1234",
"barHeight": 15.0,
"barWidth": 0.3
}
```
---
## GS1-DataMatrix-Plain
GS1-DataMatrix-Plain encodes GS1 data supplied as a plain text string using parenthesized Application Identifier (AI) notation, for example `(01)12345678901231(10)LOT001`.
## Mandatory properties
The following properties are available in addition to the [common label object properties](../common-properties).
| Property | Type | Description |
|----------|--------|------------------------------------------------------------------|
| type | string | Must be `GS1-DataMatrix-Plain`. |
| text | string | GS1 data string in parenthesized AI notation. May contain [dynamic text](../../../../dynamic-text). |
## Optional properties
The following properties are available in addition to the [DataMatrix optional properties](./data-matrix#optional-properties).
| Property | Type | Description |
|----------|---------|-----------------------------------------------------------------------------------------|
| optimize | boolean | If true, optimizes the encoding. Default is `false`. |
## Example
```json
{
"type": "GS1-DataMatrix-Plain",
"x": 10.0,
"y": 10.0,
"text": "(01)12345678901231(10)LOT001",
"moduleSize": 0.5
}
```
---
## GS1-DataMatrix
GS1-DataMatrix encodes structured GS1 data using Application Identifiers (AIs).
## Mandatory properties
The following properties are available in addition to the [common label object properties](../common-properties).
| Property | Type | Description |
|----------|--------|----------------------------------------------------------------------------------------------------------|
| type | string | Must be `GS1-DataMatrix`. |
| apps | array | Array of GS1 Application Identifier objects. Each entry has `id` (string) and `value` (string). |
## Optional properties
The same optional properties as [DataMatrix](./data-matrix) apply: `moduleSize`, `size`, `quietZone`, `extraQuietZone`, `rectangular`, `color`.
## Example
```json
{
"type": "GS1-DataMatrix",
"x": 10.0,
"y": 10.0,
"moduleSize": 0.5,
"apps": [
{"id": "01", "value": "12345678901231"},
{"id": "10", "value": "LOT001"}
]
}
```
---
## DataMatrix
## Mandatory properties
The following properties are available in addition to the [common label object properties](../common-properties).
| Property | Type | Description |
|----------|--------|------------------------------------------------------------------|
| type | string | Must be `DataMatrix`. |
| text | string | Barcode data. May contain [dynamic text](../../../../dynamic-text). |
## Optional properties
The following properties are available in addition to the [common label object properties](../common-properties).
| Property | Type | Description |
|----------------|---------|------------------------------------------------------------------------------------------------------------------|
| moduleSize | number | Size of one module (cell) in millimeters. Default is `5`. |
| size | object | Fixed symbol size in modules as `{"width": W, "height": H}`. If omitted, the minimum size that fits the data is used. |
| quietZone | boolean | Enable or disable the quiet zone. Default is `true`. |
| extraQuietZone | number | Extra quiet zone width added on all sides. |
| rectangular | boolean | If true, prefer a rectangular symbol over a square one. Default is `false`. |
| color | string | [Color](/docs/color) of the modules. May contain [dynamic text](/docs/dynamic-text). Default is `black`. |
## Example
```json
{
"type": "DataMatrix",
"x": 10.0,
"y": 10.0,
"text": "ABC-12345",
"moduleSize": 0.5
}
```
---
## EAN-13
EAN-13 encodes a 13-digit European Article Number. The check digit (last digit) is calculated automatically if omitted.
## Mandatory properties
The following properties are available in addition to the [common label object properties](../common-properties) and [common barcode properties](./barcode-common-properties).
| Property | Type | Description |
|-----------|--------|-------------------------------------------------------------------------------|
| type | string | Must be `EAN-13`. |
| text | string | 12 or 13 digits. May contain [dynamic text](../../../../dynamic-text). |
| barHeight | number | Bar height. |
## Example
```json
{
"type": "EAN-13",
"x": 10.0,
"y": 10.0,
"text": "5901234123457",
"barHeight": 20.0,
"barWidth": 0.33
}
```
---
## EAN-8
EAN-8 encodes a shortened 8-digit EAN barcode. The check digit (last digit) is calculated automatically if omitted.
## Mandatory properties
The following properties are available in addition to the [common label object properties](../common-properties) and [common barcode properties](./barcode-common-properties).
| Property | Type | Description |
|-----------|--------|---------------------------------------------------------------------|
| type | string | Must be `EAN-8`. |
| text | string | 7 or 8 digits. May contain [dynamic text](../../../../dynamic-text). |
| barHeight | number | Bar height. |
## Example
```json
{
"type": "EAN-8",
"x": 10.0,
"y": 10.0,
"text": "96385074",
"barHeight": 20.0,
"barWidth": 0.33
}
```
---
## ITF
Interleaved 2-of-5 barcode. Encodes pairs of digits; the data string must have an even number of digits.
## Mandatory properties
The following properties are available in addition to the [common label object properties](../common-properties) and [common barcode properties](./barcode-common-properties).
| Property | Type | Description |
|-----------|--------|------------------------------------------------------------------|
| type | string | Must be `ITF`. |
| text | string | Even number of digits. May contain [dynamic text](../../../../dynamic-text). |
| barHeight | number | Bar height. |
## Optional properties
The following properties are available in addition to the [common barcode properties](./barcode-common-properties).
| Property | Type | Description |
|-------------|--------|-----------------------------------------------------------------------------------------------|
| barRatio | number | Ratio of the wide bar to the narrow bar width. Default is `2.5`. |
| hBearerBar | number | Width of horizontal bearer bars (top and bottom frame bars), in multiples of `barWidth`. Default is `0` (no bearer bars). |
| vBearerBar | number | Width of vertical bearer bars (left and right frame bars), in multiples of `barWidth`. Default is `0`. |
## Example
```json
{
"type": "ITF",
"x": 10.0,
"y": 10.0,
"text": "12345678",
"barHeight": 15.0,
"barWidth": 0.5
}
```
---
## ITF-14
ITF-14 encodes a 14-digit GTIN using the Interleaved 2-of-5 symbology. The check digit is calculated and appended automatically. Horizontal bearer bars (`hBearerBar`) default to `5` to comply with the ITF-14 specification.
## Mandatory properties
The following properties are available in addition to the [common label object properties](../common-properties) and [common barcode properties](./barcode-common-properties).
| Property | Type | Description |
|-----------|--------|------------------------------------------------------------------------------------------------|
| type | string | Must be `ITF-14`. |
| text | string | 13 or 14 digits (GTIN-14). May contain [dynamic text](../../../../dynamic-text). |
| barHeight | number | Bar height. |
## Optional properties
The following properties are available in addition to the [common barcode properties](./barcode-common-properties).
| Property | Type | Description |
|------------|--------|----------------------------------------------------------------------------------------------------|
| barRatio | number | Ratio of the wide bar to the narrow bar width. Default is `2.5`. |
| hBearerBar | number | Width of horizontal bearer bars (top and bottom), in multiples of `barWidth`. Default is `5`. |
| vBearerBar | number | Width of vertical bearer bars (left and right), in multiples of `barWidth`. Default is `0`. |
## Example
```json
{
"type": "ITF-14",
"x": 10.0,
"y": 10.0,
"text": "1234567890123",
"barHeight": 20.0,
"barWidth": 0.5
}
```
---
## MaxiCode
MaxiCode is a fixed-size 2D matrix barcode used primarily by UPS for parcel routing.
## Mandatory properties
The following properties are available in addition to the [common label object properties](../common-properties).
| Property | Type | Description |
|----------|---------|-------------------------------------------------------------------------------------------------|
| type | string | Must be `MaxiCode`. |
| text | string | Barcode data. May contain [dynamic text](../../../../dynamic-text). |
| mode | integer | Encoding mode. Common values: `2` (structured carrier, numeric zip), `3` (structured carrier, alphanumeric zip), `4` (standard symbol), `5` (full ECC), `6` (reader programming). |
## Optional properties
The following properties are available in addition to the [common label object properties](../common-properties).
| Property | Type | Description |
|----------------|---------|-----------------------------------------------------------------------------------------------------------|
| fgColor | string | [Color](/docs/color) of the symbol. May contain [dynamic text](/docs/dynamic-text). Default is `black`. |
| quietZone | boolean | Enable or disable the quiet zone. Default is `true`. |
| extraQuietZone | number | Extra quiet zone width added on all sides. |
| symIndex | integer | Symbol index for structured append (1-based). Default is `0` (no structured append). |
| symTotal | integer | Total number of symbols in a structured append sequence. Default is `1`. |
## Example
```json
{
"type": "MaxiCode",
"x": 10.0,
"y": 10.0,
"text": "Example MaxiCode data",
"mode": 4
}
```
---
## PDF417
PDF417 is a stacked linear barcode capable of encoding large amounts of data.
## Mandatory properties
The following properties are available in addition to the [common label object properties](../common-properties).
| Property | Type | Description |
|----------|--------|------------------------------------------------------------------|
| type | string | Must be `PDF417`. |
| text | string | Barcode data. May contain [dynamic text](../../../../dynamic-text). |
| barWidth | number | X-dimension: width of the narrowest bar element. |
## Optional properties
The following properties are available in addition to the [common label object properties](../common-properties).
| Property | Type | Description |
|-----------------|---------|-------------------------------------------------------------------------------------------------------------------------|
| aspect | number | Row height to module width aspect ratio. If omitted, a default aspect is used. |
| rowHeight | number | Fixed row height. Overrides `aspect` if set. |
| rows | integer | Fixed number of rows. If omitted, chosen automatically. |
| columns | integer | Fixed number of data columns. If omitted, chosen automatically. |
| errorCorrection | integer | Error correction level (0–8). If omitted, chosen automatically based on data size. |
| eci | integer | ECI (Extended Channel Interpretation) value for the data encoding. Common values: `3` (ISO-8859-1), `26` (UTF-8). |
| compact | boolean | If true, use compact PDF417 (omits right-side stop pattern). Default is `false`. |
| quietZone | boolean | Enable or disable the quiet zone. Default is `true`. |
| extraQuietZone | number | Extra quiet zone added on all sides. |
| debleed | number | Ink spread compensation. |
| barColor | string | [Color](/docs/color) of the bars. May contain [dynamic text](/docs/dynamic-text). Default is `black`. |
## Example
```json
{
"type": "PDF417",
"x": 10.0,
"y": 10.0,
"text": "Hello, world!",
"barWidth": 0.5
}
```
---
## GS1-QRCode-Plain
GS1-QRCode-Plain encodes raw GS1 data supplied as a plain text string in a QR Code symbol.
## Mandatory properties
The following properties are available in addition to the [common label object properties](../common-properties).
| Property | Type | Description |
|----------|--------|------------------------------------------------------------------|
| type | string | Must be `GS1-QRCode-Plain`. |
| text | string | Raw GS1 data string. May contain [dynamic text](../../../../dynamic-text). |
## Optional properties
The following properties are available in addition to the [common label object properties](../common-properties).
| Property | Type | Description |
|----------------|---------|-------------------------------------------------------------------------------------------------------------------|
| moduleSize | number | Size of one module in millimeters. Default is `5`. |
| size | integer | Fixed symbol size in number of modules per side. If omitted, the minimum size that fits the data is used. |
| quietZone | boolean | Enable or disable the quiet zone. Default is `true`. |
| extraQuietZone | number | Extra quiet zone added on all sides. |
| color | string | [Color](/docs/color) of the dark modules. May contain [dynamic text](/docs/dynamic-text). Default is `black`. |
| eccLevel | string | Error correction level. Allowed values: `L`, `M`, `Q`, `H`. Default is `L`. |
| optimize | boolean | If true, optimizes the encoding. Default is `false`. |
## Example
```json
{
"type": "GS1-QRCode-Plain",
"x": 10.0,
"y": 10.0,
"text": "011234567890123110LOT001",
"moduleSize": 0.5
}
```
---
## GS1-QRCode
GS1-QRCode encodes structured GS1 data using Application Identifiers (AIs) in a QR Code symbol.
## Mandatory properties
The following properties are available in addition to the [common label object properties](../common-properties).
| Property | Type | Description |
|----------|--------|----------------------------------------------------------------------------------------------------------|
| type | string | Must be `GS1-QRCode`. |
| apps | array | Array of GS1 Application Identifier objects. Each entry has `id` (string) and `value` (string). |
## Optional properties
The following properties are available in addition to the [common label object properties](../common-properties).
| Property | Type | Description |
|----------------|---------|-------------------------------------------------------------------------------------------------------------------|
| moduleSize | number | Size of one module in millimeters. Default is `5`. |
| size | integer | Fixed symbol size in number of modules per side. If omitted, the minimum size that fits the data is used. |
| quietZone | boolean | Enable or disable the quiet zone. Default is `true`. |
| extraQuietZone | number | Extra quiet zone added on all sides. |
| color | string | [Color](/docs/color) of the dark modules. May contain [dynamic text](/docs/dynamic-text). Default is `black`. |
| eccLevel | string | Error correction level. Allowed values: `L`, `M`, `Q`, `H`. Default is `L`. |
## Example
```json
{
"type": "GS1-QRCode",
"x": 10.0,
"y": 10.0,
"moduleSize": 0.5,
"apps": [
{"id": "01", "value": "12345678901231"},
{"id": "10", "value": "LOT001"}
]
}
```
---
## QR Code
## Mandatory properties
The following properties are available in addition to the [common label object properties](../common-properties).
| Property | Type | Description |
|------------|---------|-----------------------------------------------------------------------|
| type | string | Must be `QRCode`. |
| text | string | Barcode data. May contain [dynamic text](../../../../dynamic-text). |
## Optional properties
The following properties are available in addition to the [common label object properties](../common-properties).
| Property | Type | Description |
|----------------|---------|-----------------------------------------------------------------------------------------------------------|
| moduleSize | number | Size of one module in millimeters. Default is `5`. |
| size | integer | Fixed symbol size in number of modules per side. If omitted, the minimum size that fits the text is used. |
| quietZone | boolean | Enable or disable the required quiet zone. Default is `true`. |
| extraQuietZone | number | Extra quiet zone. |
| color | string | [Color](../../../../color) of the nominally dark modules. May contain [dynamic text](../../../../dynamic-text). |
| eccLevel | string | Error correction level. Allowed values: `L`, `M`, `Q`, `H`. Default is `L`. |
## Example
```json
{
"type": "QRCode",
"x": 10.0,
"y": 70.0,
"text": "Hello, world!",
"moduleSize": 2.0
}
```
---
## UPC-A
UPC-A encodes a 12-digit Universal Product Code. The check digit (last digit) is calculated automatically if omitted.
## Mandatory properties
The following properties are available in addition to the [common label object properties](../common-properties) and [common barcode properties](./barcode-common-properties).
| Property | Type | Description |
|-----------|--------|----------------------------------------------------------------------|
| type | string | Must be `UPC-A`. |
| text | string | 11 or 12 digits. May contain [dynamic text](../../../../dynamic-text). |
| barHeight | number | Bar height. |
## Example
```json
{
"type": "UPC-A",
"x": 10.0,
"y": 10.0,
"text": "012345678905",
"barHeight": 20.0,
"barWidth": 0.33
}
```
---
## Common properties
## Mandatory properties
| Property | Type | Description |
|----------|--------|------------------------------------------------------------------------------|
| x | number | The distance from the left edge of the label to the horizontal anchor point. |
| y | number | The distance from the top edge of the label to the vertical anchor point. |
## Optional properties
| Property | Type | Description |
|-------------|-----------------------------|-----------------------------------------------------------------------------------|
| hAnchor | string | Horizontal anchor point. May be one of the following: `LEFT`, `CENTER`, `RIGHT`. |
| vAnchor | string | Vertical anchor point. May be one of the following: `TOP`, `CENTER`, `BOTTOM`. |
| rotate | integer | Rotation. May be one of the following: 0, 90, -90, 180. |
| hFlip | boolean | Flip horizontally. Applied before the rotation. |
| vFlip | boolean | Flip vertically. Applied before the rotation. |
| bgColor | string | Background [color](/docs/color). May contain [dynamic text](/docs/dynamic-text). |
| padding | [padding](../types/padding) | Padding around object. |
| borderColor | string | Border line [color](/docs/color). May contain [dynamic text](/docs/dynamic-text). |
| borderWidth | number | Border line width. |
---
## Ellipse
## Mandatory properties
The following properties are available in addition to the [common label object properties](./common-properties).
| Property | Type | Description |
|----------|--------|------------------------|
| type | string | Must be `Ellipse`. |
| width | number | Width of the ellipse. |
| height | number | Height of the ellipse. |
## Optional properties
| Property | Type | Description |
|-------------|---------|-------------------------------------------------------------------------------------------------------------------------|
| borderWidth | number | Border line width. |
| borderColor | string | Border line [color](/docs/color). May contain [dynamic text](/docs/dynamic-text). |
| fillColor | string | Fill [color](/docs/color). May contain [dynamic text](/docs/dynamic-text). |
| innerBorder | boolean | If true, the border is drawn inside the ellipse boundary (does not increase the overall size). Default is `false`. |
## Example
```json
{
"type": "Ellipse",
"x": 10.0,
"y": 10.0,
"width": 40.0,
"height": 20.0,
"fillColor": "black"
}
```
---
## Image(Objects)
## Mandatory properties
The following properties are available in addition to the [common label object properties](./common-properties).
| Property | Type | Description |
|----------|--------|-----------------------------------------------------------------------|
| type | string | Must be `Image`. |
| text | string | Name of the image. May contain [dynamic text](../../../dynamic-text). |
## Optional properties
The following properties are available in addition to the [common label object properties](./common-properties).
| Property | Type | Description |
|----------|----------|-----------------------------------------------------------------------------------------------------|
| width | number | Width of the image area. |
| height | number | Height of the image area. |
| hAlign | string | Horizontal alignment of the image within the image area. Allowed values: `LEFT`, `CENTER`, `RIGHT`. Default is `CENTER`. |
| vAlign | string | Vertical alignment of the image within the image area. Allowed values: `TOP`, `CENTER`, `BOTTOM`. Default is `CENTER`. |
| sizeMode | string | Scaling mode of the image within the image area. Allowed values: `RESIZE`, `SHRINK`, `STRETCH`. Default is `RESIZE`. |
| colorize | [Colorize](../types/colorize) | Print the image using a single [color](/docs/color). |
## Example
```json
{
"type": "Image",
"x": 10.0,
"y": 70.0,
"text": "MyImage"
}
```
---
## Line
## Mandatory properties
The following properties are available in addition to the [common label object properties](./common-properties).
| Property | Type | Description |
| -------- | ------ | ----------------- |
| type | string | Must be `Line`. |
| endX | number | End x coordinate. |
| endY | number | End y coordinate. |
## Optional properties
The following properties are available in addition to the [common label object properties](./common-properties).
| Property | Type | Description |
|-----------|--------|----------------------------------------------------------------------------------|
| lineWidth | number | Line width. |
| color | string | Line [color](../../../color). May contain [dynamic text](../../../dynamic-text). |
## Example
```json
{
"type": "Line",
"x": 0.0,
"y": 0.0,
"endX": 100.0,
"endY": 100.0,
"lineWidth": 5.0,
"color": "black"
}
```
---
## ObjectGroup
An ObjectGroup contains a list of child label objects that are rendered together. It has no position of its own; each child object carries its own coordinates.
## Mandatory properties
| Property | Type | Description |
|----------|--------|------------------------|
| type | string | Must be `ObjectGroup`. |
## Optional properties
| Property | Type | Description |
|----------|-------|-------------------------------------------------------------|
| children | array | Array of [label objects](./). May be empty or omitted. |
## Example
```json
{
"type": "ObjectGroup",
"children": [
{
"type": "Rect",
"x": 5.0,
"y": 5.0,
"width": 40.0,
"height": 20.0,
"fillColor": "black"
},
{
"type": "Text",
"x": 25.0,
"y": 15.0,
"hAnchor": "CENTER",
"vAnchor": "CENTER",
"text": "Hello",
"color": "white",
"font": {"family": "Arial", "style": "Regular", "height": 8.0}
}
]
}
```
---
## PolyLine
A series of connected line segments. Unlike most label objects, PolyLine does not use a position anchor — coordinates are specified directly in the `points` array.
## Mandatory properties
| Property | Type | Description |
|----------|-------|------------------------------------------------------------------------------------------------------------------|
| type | string | Must be `PolyLine`. |
| points | array | Flat array of coordinates: `[x0, y0, x1, y1, ...]`. Must contain at least 4 values (one segment). |
## Optional properties
| Property | Type | Description |
|-----------|--------|----------------------------------------------------------------------------------------------------------------------|
| lineWidth | number | Line width. Default is `1`. |
| color | string | Line [color](/docs/color). May contain [dynamic text](/docs/dynamic-text). Default is `black`. |
| segments | array | Dash pattern as alternating `[dashLength, gapLength, ...]` values. If omitted, a solid line is drawn. |
## Example
```json
{
"type": "PolyLine",
"points": [10.0, 10.0, 50.0, 10.0, 50.0, 40.0],
"lineWidth": 1.0,
"color": "black"
}
```
Dashed line example:
```json
{
"type": "PolyLine",
"points": [10.0, 20.0, 90.0, 20.0],
"lineWidth": 0.5,
"segments": [5.0, 2.0]
}
```
---
## Rectangle
## Mandatory properties
The following properties are available in addition to the [common label object properties](./common-properties).
| Property | Type | Description |
| -------- | ------ | ------------------------ |
| type | string | Must be `Rect`. |
| width | number | Width of the rectangle. |
| height | number | Height of the rectangle. |
## Optional properties
The following properties are available in addition to the [common label object properties](./common-properties).
| Property | Type | Description |
|-----------|--------|-----------------------------------------------------------------------------------------|
| lineWidth | number | Border line width. |
| lineColor | string | Border line [color](../../../color). May contain [dynamic text](../../../dynamic-text). |
| fillColor | string | Fill [color](../../../color). May contain [dynamic text](../../../dynamic-text). |
## Example
```json
{
"type": "Rect",
"x": 0,
"y": 0,
"width": 100,
"height": 100
}
```
---
## StaticBitmap
## Mandatory properties
The following properties are available in addition to the [common label object properties](./common-properties).
| Property | Type | Description |
|----------|--------|----------------------------|
| type | string | Must be `StaticBitmap`. |
| bitmap | string | Base64-encoded PNG bitmap. |
| width | number | Width of the image area. |
| height | number | Height of the image area. |
## Optional properties
The following properties are available in addition to the [common label object properties](./common-properties).
| Property | Type | Description |
|----------|--------|-------------------------------------------|
| fgColor | string | Image [color](/docs/color). |
| bgColor | string | Optional background [color](/docs/color). |
## Example
```json
{
"type": "StaticBitmap",
"x": 10.0,
"y": 10.0,
"width": 10.0,
"height": 10.0,
"bitmap": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQAAAADsdIMmAAAAD0lEQVQImWPgZ4DADxAIABHgA/2duthcAAAAAElFTkSuQmCC"
}
```
---
## Text
The text object displays single or multi-line text.
## Mandatory properties
The following properties are available in addition to the [common label object properties](./common-properties).
| Property | Type | Description |
|----------|--------|----------------------------------------------------------------------------|
| type | string | Must be `Text`. |
| text | string | Text to display. May contain [dynamic text](/docs/dynamic-text). |
| font | font | Text [font](../types/font). |
| color | string | Text [color](/docs/color). May contain [dynamic text](/docs/dynamic-text). |
## Optional properties
The following properties are available in addition to the [common label object properties](./common-properties).
| Property | Type | Description |
|---------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| width | number | Width of the text box. If present, the text will not grow beyond the width but will be word wrapped. If omitted the text will grow horizontally. |
| height | number | Height of the text box. |
| hAlign | string | Horizontal text alignment. Allowed values: `LEFT`, `CENTER`, `RIGHT`, `JUSTIFIED`. |
| vAlign | string | Vertical text alignment. Allowed values: `TOP`, `CENTER`, `BOTTOM`. |
| letterSpacing | number | Extra spacing between letters. May be negative. |
| lineSpacing | number | Extra spacing between lines. May be negative. |
| styleFormat | string | Text style language. Allowed values: `NONE`, `SIMPLE`, `ADVANCED`. Default is `NONE`. |
### Simple text style
If the `styleFormat` property is `SIMPLE`, then the text will be formatted using asterisk (`*`) characters. Text between asterisks will be highlighted by changing the font style, e.g. from Regular to Bold.
:::tip Example
```json
"text": "Ingredients: Water, sugar, *egg*, salt."
```
:::
### Advanced text style
If the `styleFormat` property is `ADVANCED`, then the text can be formatted by adding formatting blocks composed of a list of space separated key-value pairs, enclosed in square brackets. An empty formatting block will restore the previous format. Formatting can be nested.
:::tip Example
```json
"text": "Hello, [font-height=\"20mm\" color=\"red\"]huge[] world!"
```
:::
The following keys are supported:
| Key | Description |
|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `color` | Set the text color, e.g. `color="rgb(20%,70%,40%)"`. |
| `font-family` | Set the font family, e.g. `font-family="Arial"`. |
| `font-style` | Set the font style, e.g. `font-family="Bold Italic"`. |
| `font-height` | Set the font height, e.g. `font-height="20mm"`. The supported units are: "mm" for millimeters, "pt" for points and "%" for a relative size. *The unit "px" for pixels available to support legacy labels, but should not be used for new labels.* |
| `font-width` | Set the font width, e.g. `font-width="80%"`. The only supported unit is percent (%). |
## Example
```json
{
"type": "Text",
"x": 10.0,
"y": 10.0,
"text": "Hello, world!",
"color": "rgb(20%, 0%, 80%)",
"font": {
"family": "Liberation Sans",
"height": 10.0,
"style": "Bold",
"width": 1.5
}
}
```
---
## Colorize
This object specifies how to colorize an image. Colorizing an object will discard all color information in the source image, and instead only consider the darkness of each pixel. The darkness is used together with the supplied color to compute the final color.
Before the image is colorized it is converted to a black and white image. The contrast is then stretched so that the lightest color will be made completely white, and the darkest color will be made completely black.
If thresholding is enabled, then pixels with <50% gray will not be printed at all, and pixels >50% will be printed with the supplied color, effectively making the color a single color (bitmap).
If thresholding is _not_ enabled, then the darkness will detemine the amount of color for each pixel. For example, if a pixel is 35% gray, and the color is blue, then the resulting color for that pixel will be 35% blue.
| Attribute | Type | Description |
| ------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| color | string | [Color](../../../color) used to paint the object. |
| thresholding | boolean | If true, then each pixel will either not be painted at all, or it will be painted with the specified color.If false, the amount of color depends on the darkness of the pixels in the source image. |
---
## Font(Types)
The printer supports any TrueType or OpenType font. The font files must be installed in the printer before they are used.
Fonts are specified using an object with the following mandatory properties:
| Attribute | Type | Description |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------- |
| family | string | Font family name. |
| style | string | Font style name. |
| height | number | Font height. Note that this is the nominal height of the font. The height of a single character will be less. |
The following optional properties are also available:
| Attribute | Type | Description |
| --------- | ------ | ------------------------------------------------------------------------------------- |
| width | number | Horizontal stretch factor. Default is `1.0`, which is the default aspect ratio for the font. |
---
## Padding
Padding is specified using an object. All properties are optional and default to `0`.
| Attribute | Type | Description |
| --------- | ------ | --------------- |
| left | number | Left padding. |
| right | number | Right padding. |
| top | number | Top padding. |
| bottom | number | Bottom padding. |
---
## Number lookup table
## Mandatory properties
| Property | Type | Description |
| -------- | ---------------- | ------------------------------------------------------------------------------------------ |
| base | number | Numeric representation of the first string value. |
| values | array of strings | Text values to translate numbers to. The first string value corresponds to the base value. |
## Example
```json
{
"base": 2020,
"values": ["MMXX", "MMXXI", "MMXXII", "MMXXIII", "MMXXIV", "MMXXV"]
}
```
---
## Print job
The simplest form deselects any existing jobs, or selects a single label, but it can also set up a database driven job. The job can either replace the existing job, or add it to a queue.
All parameters are optional, but there needs to be one to specify the label, i.e. `labelName`, `labelColumn` or `labelData`. If any of the table parameters is used, then `tableName`, `keyColumn` and key must all be set.
| Parameter | Type | Description |
|---------------------|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| alignment | string | Alignment of the label within `targetLength`: `START`, `CENTER`, or `END`. |
| autoPrintGap | [distance](./distance) | [Auto-print](#auto-print) gap. A plain number is interpreted as nanometers. |
| autoPrintInterval | [distance](./distance) | [Auto-print](#auto-print) interval. A plain number is interpreted as nanometers. |
| checkpoint | boolean | See the [seekPrintQueueCheckpoint](/docs/aurora-api/methods/Printing/seekPrintQueueCheckpoint) API method. |
| copies | number | Limit the number of copies to print. Default is unlimited. |
| copiesColumn | string | Table column where the number of copies to print is available. |
| description | string | Description which will be displayed on the Overview tab in the user inteface. |
| firstRow | number | First table row index to use when selecting with `tableName` and `labelName`. Defaults to `0`. |
| freeze | boolean | If true, then the label will be frozen, i.e. the current label content, as well as all dynamic text, will be copies and unaffected by any changes. It will also cause all used counters to increment immediately. The default value is the value of the queue parameter. |
| hAlign | string | Along-web alignment of the label within `targetLength`, taking precedence over `alignment` when set: `LEFT`, `CENTER`, or `RIGHT`. `LEFT`/`RIGHT` map to `START`/`END` according to the print direction. |
| hOffset | [distance](./distance) | Shifts the print along the web. A plain number is interpreted as millimeters. A positive value always moves the print to the right regardless of the print direction. Applied only when `targetLength` is set, and clamped so the net change to position is never negative. |
| key | string | Value to search for in the keyColumn of the table. |
| keyColumn | string | Column in which to search to select the row to use. |
| labelName | string | The name of a label. |
| labelData | [Label](./label) | A complete label object. |
| labelColumn | string | Table column where the label name is available. |
| printDelay | [distance](./distance) | Per-job print delay override. A plain number is interpreted as millimeters. |
| printedColumn | string | Table column where to number of printed labels is stored. The value in this column will be incremented when printing. |
| queue | boolean | If true, then the label will be added to the end of the queue of jobs, else it will replace any existing queue with this job. |
| rowCount | number | Number of table rows to use when selecting with `tableName` and `labelName`. Defaults to all remaining rows from `firstRow`. |
| repeatPrintGap | [distance](./distance) | Repeat print gap. A plain number is interpreted as nanometers. |
| repeatPrintInterval | [distance](./distance) | Repeat print interval. A plain number is interpreted as nanometers. |
| roundRobin | boolean | If set, then the print job will be moved to the back of the queue when completed. |
| stepCounters | boolean | If true, step counters when the job is frozen. Default is `true`. |
| tableName | string | The name of a table. |
| targetHeight | [distance](./distance) | Target print height across the web. A plain number is interpreted as millimeters. Used together with `vAlign`. |
| targetLength | [distance](./distance) | Target print length. A plain number is interpreted as millimeters. Used together with `alignment`. |
| vAlign | string | Cross-web alignment of the label within `targetHeight`: `TOP`, `CENTER`, or `BOTTOM`. Defaults to `BOTTOM`, which matches the zero-offset position. |
## Auto-print
Auto-print is a feature that automatically triggers a job after the
previous job is completed, and the configured gap/interval has
elapsed.
:::tip
In `v4.2.0` through `v4.3.x`, if there were no other print jobs waiting in
the queue, the job was automatically printed once the configured gap/interval
had elapsed. Since `v4.4.0` this is no longer the case: if the queue is empty,
the auto-print parameters are ignored.
:::
## Examples
Deselect all print jobs (clearing the queue):
```json
{}
```
Select a single label "MyLabel":
```json
{"labelName": "MyLabel"}
```
Select a single label "MyLabel", limit to a single print, and add to the end of the queue:
```json
{
"labelName": "MyLabel",
"copies": 1,
"queue": true
}
```
Search the table "MyTable" in the column "Product" for "MyProduct", and select the label from the column "Label":
```json
{
"tableName": "MyTable",
"keyColumn": "Product",
"key": "MyProduct",
"labelColumn": "Label"
}
```
---
## Shift code
## Mandatory properties
| Property | Type | Description |
| -------- | ----- | ------------------------------- |
| shifts | array | An array with [shifts](#shift). |
## Shift
A JSON object that represent the shift properties.
| Property | Type | Description |
| -------- | ------- | ----------------------------------------------- |
| offset | integer | Number of minutes from 00:00. |
| code | string | The text to use when the current time is right. |
## Example
```json
{
"shifts": [
{
"code": "A",
"offset": 0
},
{
"code": "B",
"offset": 480
},
{
"code": "C",
"offset": 960
}
]
}
```
---
## Table
A JSON object with key/value pairs where the key represent the table and the value represent the table as an array of arrays of strings. The first array is interpreted as the headers.
## Mandatory properties
| Property | Type | Description |
| -------- | ------------------------- | -------------- |
| headers | array of strings | Table headers. |
| rows | array of array of strings | Data rows. |
## Optional properties
| Property | Type | Description |
| --------- | ------- | ---------------------------------------------------- |
| keyColumn | integer | Index of a column with optimized search performance. |
## Example
```json
{
"headers": [
"Product",
"Label",
"ID",
"Logo"
],
"keyColumn": 0,
"rows": [
[
"Carrot",
"Dark",
"100392006",
"vegetables"
],
[
"Cucumber",
"Light",
"100391895",
"vegetables"
],
[
"Squash",
"Dark",
"100391787",
"vegetables"
],
[
"Apple",
"Light",
"100391931",
"fruits"
],
[
"Orange",
"Dark",
"100391550",
"fruits"
]
]
}
```
---
## Time format
## Mandatory properties
| Property | Type | Description |
| -------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| format | string | The format used to convert a time to a text. The format is expressed using regular characters and/or [date and time components](../dynamic-text/date-and-time/components) surrounded by curly braces {}. |
## Optional properties
| Property | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------------------------------------------- |
| offset | string | An [offset](../dynamic-text/date-and-time/offsets) to apply to the time, e.g. to generate a best-before date. |
Example:
```json
{
"format": "{year}-{month}-{dayofmonth}{LF}{hour}:{minute}:{second}",
"offset": ""
}
```
---
## Variable
## Mandatory properties
| Property | Type | Description |
| -------- | ------ | ------------------ |
| value | string | The current value. |
## Optional properties
| Property | Type | Description |
| ----------- | ------- | --------------------------------------------------------------------------------------------- |
| description | string | A description that is shown in the UI instead of the name. |
| pinned | boolean | If true, the variable is pinned in the UI. |
| userEdit | boolean | If the variable shall be changeable when an operator selects a label containing the variable. |
## Example
```json
{
"description": "The logo image name",
"userEdit": true,
"value": "logo"
}
```
---
## Images
## List all available images.
```http
GET http://printer/api/v3/images
```
#### Query Parameters
| Name | Type | Description |
| ------- | ------ | ------------------------------------------------- |
| details | String | "1" or "true" to include details in the response. |
### Response
Dictionary of objects.
## Get information about an image.
```http
GET http://printer/api/v3/images/{name}/info
```
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------- |
| name | String | Label name |
### Response
| Name | Type | Description |
|-----------|--------|-----------------------------------------------------|
| fileSize | number | Image file size in bytes. |
| format | object | Image format. |
| height | number | Image height in pixels. |
| height_mm | number | Image height in millimeters. |
| intent | string | Render intent. |
| state | string | Image state. One of `PROCESSING`, `READY`, `ERROR`. |
| uid | string | Unique ID of the image. |
| width | number | Image width in pixels. |
| width_mm | number | Image width in millimeters. |
The image format has the following values:
| Name | Type | Description |
|----------------|--------|------------------------------------------------------------|
| alpha | string | Alpha channel. One of `NONE`, `STRAIGHT`, `PREMULTIPLIED`. |
| bitsPerChannel | number | Number of bits per channel. |
| channels | number | Number of channels. |
| colorSpace | string | Optional color space. One of `GRAY`, `RGB`, `CMYK`. |
## Get an image.
```http
GET http://printer/api/v3/images/{name}
```
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------- |
| name | String | Label name |
### Response
Image data.
## Delete an image.
```http
DELETE http://printer/api/v3/images/{name}
```
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------- |
| name | String | Image name |
### Response
None
## Create or replace an image.
```http
PUT http://printer/api/v3/images/{name}
```
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------- |
| name | String | Image name |
#### Query Parameters
| Name | Type | Description |
| ------ | ------ | ----------------------------------------------------------- |
| intent | String | Image rendering intent. See [Image](../json-objects/image). |
#### Headers
| Name | Type | Description |
| ------------ | ------ | ---------------------------------------------------------------------------------------------------------- |
| Content-type | String | Any of `application/json` (see [Image](../json-objects/image)), `image/jpeg`, `image/png` or `image/tiff`. |
### Response
None
---
## Import(Rest-api)
Import labels, tables, images and other objects.
```http
POST http://printer/api/v3/import
```
### Request
#### Headers
| Name | Type | Description |
| ------------ | ------ | --------------------------------------- |
| Content-Type | String | `application/json` or `application/zpl` |
#### Body
See [Import](../json-objects/import).
---
## Labels
## List all available labels
### Request
```http
GET http://printer/api/v3/labels
```
### Response
Dictionary of objects.
## Get a label
### Request
```http
GET http://printer/api/v3/labels/{name}
```
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------- |
| name | String | Label name |
### Response
Label object.
## Delete a label
### Request
```http
DELETE http://printer/api/v3/labels/{name}
```
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------- |
| name | String | Label name |
### Response
None.
## Create or modify a label
### Request
```http
PUT http://printer/api/v3/labels/{name}
```
See [Label](../json-objects/label).
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------- |
| name | String | Label name |
### Response
None.
## Get a print simulation of a label
### Request
```http
GET http://printer/api/v3/labels/{name}/simulation
```
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------- |
| name | String | Label name |
#### Query Parameters
| Name | Type | Description |
|-----------|--------|--------------------------------------|
| tableName | String | Optional table name. |
| keyColumn | String | Optional column to search for a key. |
| key | String | Optional key value to search for. |
### Response
Label object.
### Examples
Without table:
```http
GET http://printer/api/v3/labels/MyLabel/simulation
```
With table:
```http
GET http://printer/api/v3/labels/MyLabel/simulation?tableName=MyTable&keyColumn=SKU&key=12345
```
---
## Counters and history
## Get print counters
Returns the trigger and printed-label counters for a printer.
### Request
```http
GET http://printer/api/v3/printers/{name}/printCounters
```
On a single-printer system the printer name can be omitted:
```http
GET http://printer/api/v3/printCounters
```
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------ |
| name | String | Printer name |
### Response
See [getPrintCounters](/docs/aurora-api/methods/Printing/getPrintCounters).
```json
{
"triggers": 1234,
"triggerBounces": 5,
"printedLabels": 1200
}
```
## Get print history
Returns the number of labels printed over time, grouped into buckets of the
requested resolution.
### Request
```http
GET http://printer/api/v3/printers/{name}/printHistory?resolution=DAYS
```
On a single-printer system the printer name can be omitted:
```http
GET http://printer/api/v3/printHistory?resolution=DAYS
```
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------ |
| name | String | Printer name |
#### Query Parameters
| Name | Type | Description |
| ---------- | ------ | ------------------------------------------------------------------- |
| resolution | String | Bucket size: `MINUTES`, `HOURS`, `DAYS` (default), or `WEEKS`. |
| start | Number | Optional. Start of the range, in seconds since the Unix epoch. |
| end | Number | Optional. End of the range, in seconds since the Unix epoch. |
### Response
See [getPrintHistory](/docs/aurora-api/methods/Printing/getPrintHistory). The
`time` and `count` arrays are parallel: `count[i]` labels were printed during
the bucket starting at `time[i]`.
```json
{
"time": [1718668800, 1718755200, 1718841600],
"count": [120, 95, 138]
}
```
---
## Information
## List all available printers
### Request
```http
GET http://printer/api/v3/printers
```
### Response
:::note
The response is a JSON object where the keys are the names of the
printers, and the value is an object of printer properties. Different
printer models will have different properties. The output below is
just an example.
:::
```json
{
"Colorize": {
"color": "CMYKW",
"dpi": 180,
"duo": true,
"height": 108.37333299999999,
"id": "Colorize",
"physicalWidth": 210.0,
"sliceHeight": 108.37333299999999,
"slices": [
{
"inkSupplies": [
"MASTER.INKSUPPLY1",
"MASTER.INKSUPPLY2",
"MASTER.INKSUPPLY3",
"MASTER.INKSUPPLY4",
"MASTER.INKSUPPLY5"
],
"phs": [
"MASTER.PH1",
"MASTER.PH2",
"MASTER.PH3"
]
}
],
"type": "MARVIN1"
},
"TIJ": {
"color": "DUO",
"dpi": 300,
"height": 25.4,
"id": "TIJ",
"physicalWidth": 128.0,
"sliceHeight": 12.7,
"slices": [
{
"phs": [
"TIJ.PH1",
"TIJ.PH2"
]
},
{
"phs": [
"TIJ.PH3",
"TIJ.PH4"
]
}
],
"type": "TIJ1"
}
}
```
## Get printer status.
### Request
```http
GET http://printer/api/v3/printers/{name}/status
```
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------ |
| name | String | Printer name |
### Response
See [getPrinterStatus](/docs/aurora-api/methods/Information/getPrinterStatus).
---
## Printing
## Print job
The printJob endpoint is very powerful and can be used in three main modes:
* Deselecting any existing jobs by supplying an empty request body.
* Non-database section, where a label is selected using the labelName attribute. The attributes copies and queue can be used to refine the selection.
* Database selection, where tableName must be supplied. Either labelName or labelColumn must be used to select the label. The rest of the attributes can be used to refine the selection.
### Request
```http
POST http://printer/api/v3/printers/{name}/printJob
```
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------ |
| name | String | Printer name |
#### Headers
| Name | Type | Description |
| ------------ | ------ | ---------------- |
| Content-Type | string | application/json |
#### Body
See [Print job](../../json-objects/print-job).
## Abort printing
### Request
```http
POST http://printer/api/v3/printers/{name}/abortPrint
```
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------ |
| name | String | Printer name |
#### Headers
None.
#### Body
None.
## Trigger printing
### Request
```http
POST http://printer/api/v3/printers/{name}/trigger
```
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------ |
| name | String | Printer name |
#### Headers
None.
#### Body
None.
---
## Tables
## List all available tables
### Request
```http
GET http://printer/api/v3/tables
```
### Response
Dictionary of objects.
## Get a table
### Request
```http
GET http://printer/api/v3/tables/{name}
```
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------- |
| name | String | Table name |
### Response
Table object.
## Delete a table
### Request
```http
DELETE http://printer/api/v3/tables/{name}
```
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------- |
| name | String | Table name |
### Response
None.
## Create or replace a table
### Request
```http
PUT http://printer/api/v3/tables/{name}
```
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ----------- |
| name | String | Table name |
### Response
None.
---
## Variables(Rest-api)
## List all available variables.
### Request
```http
GET http://printer/api/v3/variables
```
### Response
```json
[
{
"name": "My First Variable",
"value": "ABC"
},
{
"name": "My Second Variable",
"value": "X Y Z"
}
]
```
## Get a variable.
### Request
`GET http://printer/api/v3/variables/{name}`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------- |
| name | String | Variable name |
### Response
```json
{
"description": "Optional description",
"userEdit": true,
"value": "ABC"
}
```
## Delete a variable.
### Request
`DELETE http://printer/api/v3/variables/{name}`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------- |
| name | String | Variable name |
### Response
None.
## Create or replace a variable.
### Request
`PUT http://printer/api/v3/variables/{name}`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------- |
| name | String | Variable name |
#### Headers
| Name | Type | Description |
| ------------ | ------ | ---------------- |
| Content-Type | String | application/json |
#### Body
| Name | Type | Description |
| ----------- | ------- | --------------------------------------------------------------------------------------------- |
| value | string | Variable value. |
| description | string | A description that is shown in the UI instead of the name. |
| userEdit | boolean | If the variable shall be changeable when an operator selects a label containing the variable. |
### Response
None.
---
## Examples(Aurora-api)
## Without parameter
To get the printer's version information, send the following followed by a line break:
```json
getVersion
```
Response:
```json
OK {"buildDate":"2024-09-03","hash":"bc502b158","version":"v3.0.13"}
```
## With parameter
To set the values of two variables:
```json
setVariables {"VAR1": "My first value", "VAR2": "My second value"}
```
Response:
```json
OK null
```
## Error response
Trying to get a variable that doesn't exist:
```json
getVariable "DoesNotExist"
```
Response:
```json
REQUEST_FAILED "Cannot find variable 'DoesNotExist'"
```
---
## Aurora API
This API is an easy to use text based protocol that is using JSON for serialization of data.
---
## deleteClock
Delete a clock.
## Parameter
The name of the clock to be removed.
## Return value
null
## Example
```json
deleteClock "MyClock"
```
---
## getClock
Get a clock.
## Parameter
The name of the clock to get.
## Return value
A [Clock](/docs/json-objects/clock) object. The response also includes a `name` field with the clock name.
## Example
```json
getClock "MyClock"
```
---
## listClocks
List all clocks.
## Parameter
None
## Return value
An object where the keys are clock names and the values are [Clock](/docs/json-objects/clock) objects.
## Example
```json
listClocks
```
---
## setClocks
Create or replace one or more clocks.
## Parameter
An object where the keys are clock names and the values are [Clock](/docs/json-objects/clock) objects.
## Return value
null
## Example
```json
setClocks {"MyClock": {"dateTime": {"year": 2026, "month": 5, "day": 16}}}
```
---
## deleteCounter
Delete a counter.
## Parameter
The name of the counter to be removed.
## Return value
null
## Example
```json
deleteCounter "My Counter"
```
---
## getCounter
Get a counter.
## Parameter
The name of the counter to get.
## Returns
A [Counter](/docs/json-objects/counter) object, with an additional `name` key holding the counter name.
## Example
```json
getCounter "My Counter"
```
---
## listCounters
List all counters.
## Parameter
None
## Returns
An object where the keys are counter names, and value values are [Counter](/docs/json-objects/counter) objects.
## Example
```json
listCounters
```
---
## setCounters
Create or replace one or more counters.
## Parameter
An object where the keys are counter names, and the values are [Counter](/docs/json-objects/counter) objects.
## Return value
null
## Example
```json
setCounters {"CNT1": {"minValue": 0, "maxValue": 9999, "width": 4}}
```
---
## stepCounters
Step one or more counters by one increment.
## Parameter
| Key | Type | Description |
|---------|------------------|----------------------------------------------------------------------|
| names | array of strings | Names of the counters to step. |
| reverse | boolean | Optional. Step backwards (decrement) instead of forwards. Default `false`. |
## Return value
null
## Example
```json
stepCounters {"names": ["My Counter"]}
```
---
## copyImages
Copy one or more images.
## Parameter
An object where the keys are existing image names, and the values are their new names.
## Return value
null
## Example
```json
copyImages {"Old Name": "New Name"}
```
---
## deleteImage
Delete an image.
## Parameter
The name of the image to be removed.
## Return value
null
## Example
```json
deleteImage "My Image"
```
---
## getImage
Get a image.
## Parameter
The name of the image to get.
## Returns
An object with the following keys:
| Key | Type | Description |
|----------|--------|------------------------------------|
| fileName | string | Original file name of the image. |
| data | string | Base64-encoded original file data. |
| intent | string | Storage intent. |
## Example
```json
getImage "My Image"
```
---
## getImageInfo
Get metadata for an image.
## Parameter
The name of the image.
## Return value
| Key | Type | Description |
|--------------|---------|---------------------------------------------------------|
| uid | string | Unique identifier. |
| intent | string | Storage intent. |
| created | number | Creation timestamp (Unix time, seconds). |
| fileSize | number | File size in bytes. |
| memoryUsage | number | Memory usage in bytes. |
| state | string | Load state of the image. |
| previewState | string | Load state of the image preview. |
| active | boolean | Whether the image is currently active. |
| width | number | Image width in pixels (present when dimensions are known). |
| height | number | Image height in pixels (present when dimensions are known). |
| format | object | Pixel format object, see [listImages](./listImages) (present when dimensions are known). |
| width_mm | number | Image width in millimeters (present when dimensions are known). |
| height_mm | number | Image height in millimeters (present when dimensions are known). |
| profile | string | Color profile (present when dimensions are known). |
## Example
```json
getImageInfo "MyImage"
```
---
## listImages
List all images.
## Parameter
None
## Returns
An object where the keys are image names, and value values are objects with the following keys:
| Key | Type | Description |
| ------------ | ------- | ----------------------------------------------------------------------- |
| uid | string | Unique ID of the image. |
| intent | string | Storage intent. |
| created | number | Creation timestamp (Unix time, seconds). |
| fileSize | number | Image file size in bytes. |
| memoryUsage | number | Memory usage in bytes. |
| state | string | Load state of the image. |
| previewState | string | Load state of the image preview. |
| active | boolean | Whether the image is currently active. |
| width | number | Image width in pixels (present when dimensions are known). |
| height | number | Image height in pixels (present when dimensions are known). |
| format | object | Image format, see below (present when dimensions are known). |
| width_mm | number | Image width in millimeters (present when dimensions are known). |
| height_mm | number | Image height in millimeters (present when dimensions are known). |
| profile | string | Embedded image color profile name (present when dimensions are known). |
The image format object has the following keys:
| Key | Type | Description |
| -------------- | ------ | ---------------------------------------------------------- |
| colorSpace | string | GRAY, RGB, or CMYK. Omitted if the color space is unknown. |
| alpha | string | NONE, STRAIGHT, or PREMULTIPLIED. |
| channels | number | Number of channels. |
| bitsPerChannel | number | Number of bits per channel. |
## Example
```json
listImages
```
---
## renameImages
Rename one or more images.
## Parameter
An object where the keys are existing image names, and the values are their new names.
## Return value
null
## Example
```json
renameImages {"Old Name": "New Name"}
```
---
## resizeImage
Resize an images.
## Parameter
| Key | Type | Description |
| ------- | ------ | --------------------------- |
| name | string | Name of image to rename. |
| newName | string | Optional new image name. |
| width | number | New image width in pixels. |
| height | number | New image height in pixels. |
## Return value
null
## Example
```json
resizeImage {"name": "MyImage", "newName": "ResizedImage", "width": 200, "height": 100}
```
---
## setImageActive
Activate or deactivate one or more images.
## Parameter
An object where the keys are image names and the values are booleans.
## Return value
null
## Example
```json
setImageActive {"MyImage": true}
```
---
## setImageIntent
Set the storage intent for one or more images.
## Parameter
An object where the keys are image names and the values are intent strings.
## Return value
null
## Example
```json
setImageIntent {"MyImage": "PERMANENT"}
```
---
## setImages
Create or replace one or more images.
## Parameter
An object where the keys are image names, and the values are [Image](/docs/json-objects/image) objects.
## Return value
null
---
## waitForImage
Wait for a image to be ready for printing, or for any errors processing the image. This call will block while the image is being processed. If the image is ready when making this call, it will return immediately.
## Parameter
The name of the image to wait for (a bare string), or an object:
| Key | Type | Description |
|---------|--------|---------------------------------------------------------------|
| name | string | The name of the image to wait for. |
| printer | string | Printer ID. Required if more than one printer is available. |
## Returns
The final state of the image: `READY`, `ERROR`, or `OUT_OF_MEMORY`.
## Example
```json
waitForImage "My Image"
```
---
## export
## Parameter
An object with the following keys:
| Key | Type | Desctription |
| ----------- | ---------------- | ---------------------------------------------------------- |
| options | object | An object with options that affect how items are exported. |
| counters | array of strings | An array of names of counters to export. |
| variables | array of strings | An array of names of variables to export. |
| shiftcodes | array of strings | An array of names of shift codes to export. |
| clocks | array of strings | An array of names of clocks to export. |
| timeformats | array of strings | An array of names of time formats to export. |
| numberFormats | array of strings | An array of names of number formats to export. |
| tables | array of strings | An array of names of tables to export. |
| fonts | array of strings | An array of names of font files to export. |
| images | array of strings | An array of names of images to export. |
| labels | array of strings | An array of names of labels to export. |
The options object has the following keys:
| Key | Type | Desctription |
| ------------- | ------- | ---------------------------------------------------------------------------------------------- |
| includeImages | boolean | If true, include any images that are used by the labels selected in the export. Default false. |
| includeFonts | boolean | If true, include any fonts that are used by the labels selected in the export. Default false. |
| includeDynamicText | boolean | If true, include the dynamic text resources (counters, variables, etc.) used by the labels selected in the export. Default false. |
## Return value
An object with the same keys as the parameter (only those with exported items are present). Each value contains the exported items, in a form suitable for passing to [import](./import).
---
## import(Import and export)
Imports various files and objects.
## Parameter
An [Import](/docs/json-objects/import) object.
## Return value
An object containing information about what was successfully imported.
## Examples
Import a variable and a label (expanded to multiple lines to improved readability):
```json
"variables": {
"My Variable": {
"value": "My Value"
}
},
"labels": {
"My Label": {
"metric": true,
"height": 108,
"width": 200,
"objs": [
{
"type": "Rect",
"x": 55,
"y": 38,
"height": 30,
"width": 30,
"fillColor": "black"
},
{
"type": "Text",
"x": 0,
"y": 0,
"text": "Hello {VARIABLE;My Variable}",
"color": "black",
"font": {
"family": "Liberation Sans",
"style": "Regular",
"height": 20
}
}
]
}
}
}
```
Returns:
```json
OK {"labels":["My Label"],"variables":["My Variable"]}
```
---
## getPrinterState
Get the current state of a printer.
## Parameter
| Key | Type | Description |
|---------|--------|-------------|
| printer | string | Printer ID. |
## Return value
Get current state of the machine as a string:
| State | Description | Printing possible |
| -------------- | ------------------------------------------------------------------------------------------- | ----------------- |
| `INITIALIZING` | The printer is initializing. | false |
| `STOPPED` | The printer is stopped. | false |
| `STANDBY` | The printer is in standby mode. | false |
| `STARTING` | The ink systems are starting. Next state is HEATING. | false |
| `HEATING` | The ink systems are started up, but the operating ink temperature has not yet been reached. | true |
| `STARTED` | The ink systems are started and the printer is ready to print. | true |
| `MAINTENANCE` | The operator mode en enabled, which prevents printing. | false |
| `STOPPING` | The ink systems are stopping. | false |
| `ERROR` | An error has occurred. | false |
| `OTHER` | The ink systems are in a mixed state, i.e. one is running and another is stopped. | false |
---
## getPrinterStatus
Get the current status of a printer.
## Parameter
| Key | Type | Description |
|---------|--------|-------------|
| printer | string | Printer ID. |
## Return value
A Status object with the following keys:
| Key | Type | Description |
|-----------|--------------------|-------------------------------------------|
| state | string | See [getPrinterState](./getPrinterState). |
| ragStatus | string | RED, AMBER or GREEN. |
| errors | array of strings | Empty if there are no errors. |
| ink | array of InkStatus | See below. |
| position | number | Current position in meters. Present only when known. |
| speed | number | Current speed in meters per second. Present only when known. |
For Marvin1 printers, an InkStatus object has the following keys:
| Key | Type | Description |
| --------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- |
| state | string | `STOPPED`, `STANDBY`, `STARTING`, `STARTED`, `STOPPING`, `CALIBRATING`, `FILLING`, `EMPTYING`, `MANUAL`, or `ERROR`. |
| ragStatus | string | `RED`, `AMBER` or `GREEN`. |
| level | string | `EMPTY`, `LOW`, or `OK`. Present only when known. |
| errors | array of strings | Empty if there are no errors. |
| warnings | array of strings | Empty if there are no warnings. |
For TIJ1 printers, an InkStatus object instead has the following keys:
| Key | Type | Description |
| --------- | ------- | ------------------------------------------------------- |
| phState | string | Printhead state. |
| crtState | string | Cartridge state. |
| ragStatus | string | `RED`, `AMBER` or `GREEN`. |
| inkLevel | number | Cartridge ink level. Present only when known. |
| inkLow | boolean | Whether the cartridge ink is low. Present only when known. |
---
## getSpeedInfo
Get the current position and speed of a printer.
## Parameter
| Key | Type | Description |
|---------|--------|-------------|
| printer | string | Printer ID. |
## Return value
An object with the following keys:
| Key | Type | Description |
|----------|--------|-------------------------------------|
| position | number | Current position in meters. |
| speed | number | Current speed in meters per second. |
---
## getVersion
Get the current software version of the controller.
## Parameter
None.
## Return value
An object with the following keys:
| Key | Type | Description |
| --------- | ------ | -------------------- |
| version | string | Software version. |
| hash | string | Software hash. |
| buildDate | string | Software build date. |
---
## listPrinters
List all available printers and their properties.
## Parameter
None
## Return value
An object where the keys are printer IDs and the values are printer info objects.
## Example
```json
listPrinters
```
---
## getGpi
Get the state of a general purpose input.
## Parameter
The name of the input.
## Return value
An object with the following keys:
| Key | Type | Description |
| ----- | ------- | -------------- |
| state | boolean | Current state. |
---
## getGpioCondition
Get the current state of a GPIO condition.
## Parameter
The name of the GPIO condition.
## Return value
| Key | Type | Description |
|-------|---------|------------------------------|
| state | boolean | Current state of the condition. |
## Example
```json
getGpioCondition "MyCondition"
```
---
## getPrintDirection
Get the current print direction.
## Parameter
Printer ID. Required if more than one printer is available.
## Return value
| Key | Type | Description |
|-----------|--------|------------------------------------------|
| direction | string | `"LTR"` (left-to-right) or `"RTL"` (right-to-left). |
## Example
```json
getPrintDirection
```
---
## Input/output
:::tip
Output signals cannot be set directly. Instead, *conditions* are tied to actual output pins using the printer settings, and the API sets the conditions.
:::
GPIO conditions you define from the API come in two kinds :
- **User conditions** — named boolean values set directly with [setGpioConditions](./setGpioConditions). They persist across restarts, are listed with [listUserGpioConditions](./listUserGpioConditions), and removed with [removeUserGpioCondition](./removeUserGpioCondition).
- **User expressions** — named boolean expressions derived from other conditions, managed with [setUserGpioExpressions](./setUserGpioExpressions), [listUserGpioExpressions](./listUserGpioExpressions), and [removeUserGpioExpression](./removeUserGpioExpression).
Use [listGpioConditions](./listGpioConditions) for the current state of every condition and expression, and [listWritableGpioConditions](./listWritableGpioConditions) for the conditions whose state can be set via the API.
## Built-in conditions
Besides the conditions and expressions you define, the system maintains
read-only built-in conditions that reflect printer status. Each printer exposes
its own conditions named `printer..` (for example
`printer.Colorize.printing`), and matching aggregate conditions named
`printers.` combine that condition across all printers (for example
`printers.printing`). Use [listGpioConditions](./listGpioConditions) to see which
conditions are available.
---
## listCustomGpioConditions
:::warning Deprecated
Since v5.0, user conditions and expressions are managed separately. Use [listUserGpioConditions](./listUserGpioConditions) and [listUserGpioExpressions](./listUserGpioExpressions) instead.
:::
List all custom GPIO conditions.
## Parameter
None
## Return value
An object where the keys are custom condition names and the values are either their boolean state (for conditions) or their expression string (for expressions).
## Example
```json
listCustomGpioConditions
```
---
## listGpi
List all general purpuse inputs and their state.
## Parameter
None.
## Return value
An object where the keys are the input names and the values are objects with the following keys:
| Key | Type | Description |
|-----------|---------|------------------------------------------------------------------|
| edgeCount | number | Number of edges (state changes) detected. |
| state | boolean | Current input state. Present only when known. |
| active | boolean | Whether the input is currently active. Present only when known. |
---
## listGpioConditions
List all GPIO conditions.
## Parameter
None.
## Return value
An object with the conditions as keys and their current boolean state as value.
---
## listUserGpioConditions
List the user-defined GPIO conditions.
## Parameter
None.
## Return value
An object where the keys are user condition names and the values are their current boolean state.
---
## listUserGpioExpressions
List the user-defined GPIO expressions.
## Parameter
None.
## Return value
An object where the keys are expression names and the values are their expression strings.
---
## listWritableGpioConditions
List the GPIO conditions whose state can be set via the API (see [setGpioConditions](./setGpioConditions)).
## Parameter
None.
## Return value
An object where the keys are condition names and the values are their current boolean state.
---
## removeCustomGpioCondition
:::warning Deprecated
Since v5.0, user conditions and expressions are managed separately. Use [removeUserGpioCondition](./removeUserGpioCondition) or [removeUserGpioExpression](./removeUserGpioExpression) instead.
:::
Remove a custom GPIO condition.
## Parameter
The name of the custom condition to be removed.
## Return value
null
---
## removeUserGpioCondition
Remove a user-defined GPIO condition.
## Parameter
The name of the user condition to remove.
## Return value
null
---
## removeUserGpioExpression
Remove a user-defined GPIO expression.
## Parameter
The name of the user expression to remove.
## Return value
null
---
## setCustomGpioConditions
:::warning Deprecated
Since v5.0, user conditions and expressions are managed separately. Use [setGpioConditions](./setGpioConditions) for boolean conditions and [setUserGpioExpressions](./setUserGpioExpressions) for expressions instead.
:::
Set one or more custom GPIO conditions.
## Parameter
An object where the keys are custom condition names, and each value is either:
- a **boolean** — a fixed condition state, or
- a **string** — a condition expression that is evaluated to derive the state.
## Return value
null
---
## setGpioConditions
Set the state of one or more writable GPIO conditions. A condition that does not yet exist is created as a user condition; an existing condition must be writable.
## Parameter
An object where the keys are condition names and the values are their boolean state.
## Return value
null
## Example
```json
setGpioConditions {"MyCondition": true}
```
---
## setPrintDirection
Set the print direction.
## Parameter
| Key | Type | Description |
|-----------|--------|-----------------------------------------------------------------|
| direction | string | `"LTR"` (left-to-right) or `"RTL"` (right-to-left). |
| printer | string | Printer ID. Required if more than one printer is available. |
## Return value
null
## Example
```json
setPrintDirection {"direction": "RTL"}
```
---
## setUserGpioExpressions
Set one or more user-defined GPIO expressions. An expression is a boolean expression derived from other conditions.
## Parameter
An object where the keys are expression names and the values are expression strings.
## Return value
null
## Example
```json
setUserGpioExpressions {"MyExpression": "printer.ready and not device.in1"}
```
---
## waitForGpi
Get the state of a general purpose input.
## Parameter
An object with the following keys:
| Key | Type | Description |
| ------- | ------- | ---------------------------- |
| name | string | Name of input. |
| state | boolean | State to wait for. |
| timeout | number | Optional timeout in seconds. |
## Return value
True if the state was found, or false if timed out.
---
## waitForGpioCondition
Wait until a GPIO condition reaches the specified state.
## Parameter
| Key | Type | Description |
|---------|---------|------------------------------------------------------------|
| name | string | Name of the GPIO condition. |
| state | boolean | The state to wait for. |
| timeout | number | Optional timeout in seconds. If omitted, waits forever. |
## Return value
`true` if the condition reached the desired state; `false` if the timeout elapsed before the state was reached.
## Example
```json
waitForGpioCondition {"name": "MyCondition", "state": true, "timeout": 5.0}
```
---
## copyLabels
Copy one or more labels.
## Parameter
An object where the keys are existing label names, and the values are their new names.
## Return value
null
#### Example
```json
copyLabels {"Old Name": "New Name"}
```
---
## deleteLabel
Delete a label.
## Parameter
The name of the label to be removed.
## Return value
null
## Example
```json
deleteLabel "My Label"
```
---
## getLabel
Get a label.
## Parameter
The name of the label to get.
## Returns
A [Label](/docs/json-objects/label) object.
## Example
```json
getLabel "My Label"
```
---
## getLabelSimulation
Render a label to an image.
## Parameter
| Key | Type | Description |
|-----------|--------|----------------------------------------------------------------------------------------------|
| labelName | string | Name of the label in the database. Mutually exclusive with `labelData`. |
| labelData | object | A [Label](/docs/json-objects/label/intro) object. Mutually exclusive with `labelName`. |
| printer | string | Optional printer ID. When specified, uses that printer's fonts and resolution for rendering. |
| tableName | string | Optional table to source variable values from when rendering. |
| keyColumn | string\|number | Optional column in `tableName` to match against `key`. Requires `tableName` and `key`. |
| key | string | Optional value to look up in `keyColumn` to select the table row. Requires `tableName` and `keyColumn`. |
## Return value
| Key | Type | Description |
|----------|--------|------------------------------------|
| data | string | Base64-encoded PNG image data. |
| width | number | Image width in pixels. |
| height | number | Image height in pixels. |
| mimeType | string | Always `"image/png"`. |
## Example
```json
getLabelSimulation {"labelName": "MyLabel"}
```
---
## listLabels
List the names of all labels.
## Parameter
None
## Returns
An array of label name strings.
See [listLabels2](./listLabels2) to also get information about each label.
## Example
```json
listLabels
```
---
## listLabels2
List all labels.
## Parameter
None
## Returns
An object where the keys are label names, and value values are objects with information about the label.
## Example
```json
listLabels2
```
---
## renameLabels
Rename one or more labels.
## Parameter
An object where the keys are existing label names, and the values are their new names.
## Return value
null
## Example
```json
renameLabels {"Old Name": "New Name"}
```
---
## setLabels
Create or replace one or more labels.
## Parameter
An object where the keys are label names, and the values are [Label](/docs/json-objects/label) objects.
## Return value
null
---
## transformLabel
Apply geometric transformations to a label (rotate, flip, scale, translate).
## Parameter
| Key | Type | Description |
|--------------|---------|----------------------------------------------------------------------------------------------------------|
| labelName | string | Name of the label in the database. Mutually exclusive with `labelData`. |
| labelData | object | A [Label](/docs/json-objects/label/intro) object. Mutually exclusive with `labelName`. |
| scale | number | Scale factor. Default is `1.0`. |
| flipX | boolean | Mirror horizontally. Default is `false`. |
| flipY | boolean | Mirror vertically. Default is `false`. |
| transpose | boolean | Swap X and Y axes. Default is `false`. |
| rotation | string | Rotation: `"NONE"`, `"CW90"`, `"CW180"`, or `"CCW90"`. Default is `"NONE"`. |
| dx | number | Horizontal translation in millimeters. |
| dy | number | Vertical translation in millimeters. |
| newLabelName | string | If provided, saves the transformed label to the database under this name and returns null. |
## Return value
If `newLabelName` is provided, the transformed label is saved to the database and null is returned. Otherwise, the transformed [Label](/docs/json-objects/label/intro) object is returned.
## Example
Rotate a label 90 degrees and save under a new name:
```json
transformLabel {"labelName": "MyLabel", "rotation": "CW90", "newLabelName": "MyLabel-Rotated"}
```
---
## deleteNumberFormat
Delete a number format.
## Parameter
The name of the number format to be removed.
## Return value
null
## Example
```json
deleteNumberFormat "MyWeekday"
```
---
## getNumberFormat
Get a number format.
## Parameter
The name of the number format to get.
## Returns
A [Number format](/docs/json-objects/number-lookup-table) object.
## Example
```json
getNumberFormat "shortweekday"
```
---
## listNumberFormats
List all number formats.
## Parameter
None
## Returns
An object where the keys are number format names, and the values are [Number format](/docs/json-objects/number-lookup-table) objects. Each value also includes a `builtin` boolean indicating whether it is a built-in format.
## Example
```json
listNumberFormats
```
---
## setNumberFormats
Create or replace one or more number formats.
## Parameter
An object where the keys are number format names, and the values are [Number format](/docs/json-objects/number-lookup-table) objects.
## Return value
null
## Example
```json
setNumberFormats {"MyWeekday": {"base": 1, "values": ["MÅ","TI","ON","TO","FR","LÖ","SÖ"]}}
```
---
## abortPrint
Immediately aborts any active printing. Does not clear the print job queue. In most situations, it is recommended to clear the queue using the selectPrintJob method, before calling abortPrint.
## Parameter
| Key | Type | Description |
|---------|--------|-------------------------------------------------------------|
| printer | string | Printer ID. Required if more than one printer is available. |
## Return value
null
---
## getCurrentPrintJob
Get the current print job.
## Parameter
| Key | Type | Description |
|---------|--------|-------------------------------------------------------------|
| printer | string | Printer ID. Required if more than one printer is available. |
## Return value
Null if nothing is selected, or [Print job](/docs/json-objects/print-job) object.
---
## getPrintCounters
Get the print counters for a printer.
## Parameter
| Key | Type | Description |
|---------|--------|-------------------------------------------------------------|
| printer | string | Printer ID. Required if more than one printer is available. |
## Return value
| Key | Type | Description |
|----------------|--------|------------------------------------------------------|
| triggers | number | Total number of trigger edge events. |
| triggerBounces | number | Number of debounced (filtered) edge events. |
| printedLabels | number | Total number of labels printed. |
## Example
```json
getPrintCounters {"printer": "printer1"}
```
---
## getPrintHistory
Get the print history (number of labels printed over time) for a printer.
The history is returned as buckets of the requested resolution. Each bucket
reports how many labels were printed during the period that starts at its
timestamp.
## Parameter
| Key | Type | Description |
|------------|--------|-------------------------------------------------------------------------|
| printer | string | Printer ID. Required if more than one printer is available. |
| resolution | string | Bucket size: `MINUTES`, `HOURS`, `DAYS`, or `WEEKS`. |
| start | number | Optional. Start of the range, in seconds since the Unix epoch. |
| end | number | Optional. End of the range, in seconds since the Unix epoch. |
## Return value
Two parallel arrays of equal length. For each index `i`, `count[i]` is the
number of labels printed during the bucket that starts at `time[i]`.
| Key | Type | Description |
|-------|-----------------|------------------------------------------------------|
| time | array of number | Bucket start times, in seconds since the Unix epoch. |
| count | array of number | Number of labels printed during each bucket. |
## Example
```json
getPrintHistory {"printer": "printer1", "resolution": "DAYS"}
```
---
## getPrintQueueLength
Get the number of labels in the print queue.
## Parameter
| Key | Type | Description |
|---------|--------|-------------------------------------------------------------|
| printer | string | Printer ID. Required if more than one printer is available. |
## Return value
Number of labels as a number.
---
## getTrigger
Get counter information for a trigger.
## Parameter
| Key | Type | Description |
|---------|--------|-------------------------------------------------------------------------|
| id | string | Trigger ID. If omitted, the trigger of `printer` is used. |
| printer | string | Printer ID. Used when `id` is omitted; required if more than one printer is available. |
## Return value
| Key | Type | Description |
|---------------|---------|------------------------------------------------------|
| edgeCounter | number | Total number of trigger edge events. |
| activeCounter | number | Number of times the trigger became active. |
| bounceCounter | number | Number of debounced (filtered) edge events. |
| active | boolean | Current active state of the trigger. |
## Example
```json
getTrigger {"id": "trigger1"}
```
---
## seekPrintQueueCheckpoint
Skip print jobs at the head of the queue until a checkpoint job is reached. Primarily used with round-robin printing to reset the sequence to the initial label.
## Parameter
| Key | Type | Description |
|---------|--------|-------------------------------------------------------------|
| printer | string | Printer ID. Required if more than one printer is available. |
## Return value
None.
---
## selectPrintJob
The selectPrintJob method is a very powerful method that allows control of what to print. The simplest form deselects any existing jobs, or selects a single label, but it can also set up a database driven job. The job can either replace the existing job, or add it to a queue.
## Parameter
A [Print job](/docs/json-objects/print-job) object.
The Print job object must also include the following attributes:
| Key | Type | Description |
|---------|--------|-------------------------------------------------------------|
| printer | string | Printer ID. Required if more than one printer is available. |
## Return value
null
## Examples
Deselect all print jobs (clearing the queue):
```json
selectPrintJob {}
```
Select a single label "MyLabel":
```json
selectPrintJob {"labelName": "MyLabel"}
```
Select a single label "MyLabel", limit to a single print, and add to the end of the queue:
```json
selectPrintJob {"labelName": "MyLabel", "copies": 1, "queue": true}
```
Search the table "MyTable" in the column "Product" for "MyProduct", and select the label from the column "Label":
```json
selectPrintJob {"tableName": "MyTable", "keyColumn": "Product", "key": "MyProduct", "labelColumn": "Label"}
```
---
## setFixedSpeed
Override the print speed with a fixed value. This disables encoder-based speed tracking and drives the printhead at the given constant speed.
## Parameter
| Key | Type | Description |
|---------|--------|---------------------------------------------------------------|
| speed | number | Fixed print speed in meters per second. |
| printer | string | Printer ID. Required if more than one printer is available. |
## Return value
null
## Example
```json
setFixedSpeed {"speed": 0.5}
```
---
## trigger
Trigger a print, either by generating a pulse, or setting the trigger level, which can be used with the terminate feature to start and stop printing.
## Parameter
| Key | Type | Description |
|---------|---------|----------------------------------------------------------------------------------|
| printer | string | Printer ID. Required if more than one printer is available. |
| active | boolean | If present will set the trigger level. A pulse will be generated if not present. |
| position | number | Optional encoder position to trigger at. If omitted, triggers immediately. |
## Return value
null
---
## waitForTrigger
Wait until a trigger reaches the specified active state.
## Parameter
| Key | Type | Description |
|---------|---------|----------------------------------------------------------|
| id | string | Trigger ID. If omitted, the trigger of `printer` is used. |
| printer | string | Printer ID. Used when `id` is omitted; required if more than one printer is available. |
| state | boolean | The active state to wait for. Required. |
| timeout | number | Timeout in seconds. Required. |
## Return value
`{position: number}` with the encoder position at the moment the trigger fired, or `null` if the timeout elapsed before the trigger fired.
## Example
```json
waitForTrigger {"id": "trigger1", "state": true, "timeout": 5.0}
```
---
## getPrinterSettings
Get the current settings of the printer.
## Parameter
| Key | Type | Description |
|---------|--------|------------------------------------|
| printer | string | Printer ID. Required if more than one printer is available. |
## Return value
An object with all printer settings.
:::info
The available settings depends on the software version. Settings may be added, removed or renamed when software is updated.
:::
---
## setPrinterSettings
Modify the settings of the printer.
## Parameter
| Key | Type | Description |
|----------|--------|------------------------------------------------------------------------|
| settings | object | A partial Settings object. Any settings not included remain unchanged. |
| printer | string | Printer ID. Required if more than one printer is available. |
## Return value
None
---
## deleteShiftCode
Delete a shift code.
## Parameter
The name of the shift code to be removed.
## Return value
null
## Example
```json
deleteShiftCode "My Counter"
```
---
## getShiftCode
Get a shift code.
## Parameter
The name of the shift code to get.
## Returns
A [Shift code](/docs/json-objects/shift-code) object.
## Example
```json
getShiftCode "My Shift Code"
```
---
## listShiftCodes
List all shift codes.
## Parameter
None
## Returns
An object where the keys are shift code names, and value values are [Shift code](/docs/json-objects/shift-code) objects.
## Example
```json
listShiftCodes
```
---
## setShiftCodes
Create or replace one or more shift codes.
## Parameter
An object where the keys are shift code names, and the values are [Shift code](/docs/json-objects/shift-code) objects.
## Return value
null
## Example
```json
setShiftCodes {"SHIFT": {"shifts": [{"offset": 360, "code": "DAY"}, {"offset": 1080, "code": "NIGHT"}]}}
```
---
## appendTables
Append rows to one or more tables.
## Parameter
An object where the keys are table names, and the values are [Table](/docs/json-objects/table) objects.
## Return value
null
---
## copyTables
Copy one or more tables.
## Parameter
An object where the keys are existing table names, and the values are their new names.
## Return value
null
## Example
```json
copyTables {"Old Name": "New Name"}
```
---
## deleteTable
Delete a table.
## Parameter
The name of the table to be removed.
## Return value
null
## Example
```json
deleteTable "My table"
```
---
## getTable
Get a table.
## Parameter
The name of the table (a bare string), or an object:
| Key | Type | Description |
|----------|--------|-----------------------------------------------------------------|
| name | string | Table name. |
| firstRow | number | Optional first row index to return. Default is `0`. |
| maxRows | number | Optional maximum number of rows to return. Default is all rows. |
## Returns
A [Table](/docs/json-objects/table) object, with these additional keys:
| Key | Type | Description |
|-------------|--------|--------------------------------------|
| uid | string | Unique identifier of the table. |
| memoryUsage | number | Memory usage in bytes. |
| modified | number | Last-modified timestamp (Unix time). |
## Example
```json
getTable "My Image"
```
---
## getTableColumn
Get columns from a table.
## Parameter
An object with the following keys:
| Key | Type | Description |
| ------ | ---------------- | ------------------------------------------------------------------------------ |
| name | string | Table name. |
| column | string or number | The column to return, specified by either the header, or the column index. |
| index | number | Optional first row index, where the first row has index zero. Default is zero. |
| count | number | Optional number of rows to return. Default is all rows. |
| unique | boolean | Optional. If true, omit duplicate values. Default is `false`. |
#### Returns
An array of cell values as strings. The cell from the header is not included.
---
## getTableInfo
Get information about a table.
## Parameter
The name of the table.
## Returns
An object with the following keys:
| Key | Type | Description |
| ------------- | ---------------- | ------------------------------------------------- |
| name | string | Table name. |
| uid | string | Unique identifier of the table. |
| rowCount | number | Number of rows, not including the headers. |
| columnCount | number | Number of columns. |
| memoryUsage | number | Memory usage in bytes. |
| modified | number | Last-modified timestamp (Unix time). |
| headers | array of strings | The table headers. |
| keyColumn | number | Index of the key column. Present only if set. |
| columnFormats | array | Per-column format objects. |
---
## getTableRow
Get a single row from a table.
## Parameter
| Key | Type | Description |
|-----------|----------------|----------------------------------------------------------------------------------|
| name | string | Table name. |
| index | number | Zero-based row index. Mutually exclusive with `keyColumn` + `key`. |
| keyColumn | string | Column to search in. Mutually exclusive with `index`. |
| key | string\|number | Value to match in `keyColumn`. Required when `keyColumn` is specified. |
## Return value
An object mapping column names to their values for the matched row.
## Examples
Get row by index:
```json
getTableRow {"name": "MyTable", "index": 0}
```
Get row by key lookup:
```json
getTableRow {"name": "MyTable", "keyColumn": "Product", "key": "MyProduct"}
```
---
## getTableRows
Get rows from a table.
## Parameter
An object with the following keys:
| Key | Type | Description |
| ----- | ------ | ------------------------------------------------------------------------------ |
| name | string | Table name. |
| index | number | Optional first row index, where the first row has index zero. Default is zero. |
| count | number | Optional number of rows to return. Default is all rows. |
## Returns
A [Table](/docs/json-objects/table) object.
---
## listTables
List all tables.
## Parameter
None
## Returns
An object where the keys are table names, and value values are objects with information about the table.
---
## modifyTableCell
Modify a single cell in a table. Optionally supports compare-and-swap: if `expectedValue` is provided, the update only proceeds if the cell currently holds that value.
## Parameter
| Key | Type | Description |
|---------------|----------------|----------------------------------------------------------------------------------|
| name | string | Table name. |
| rowIndex | number | Zero-based row index. Mutually exclusive with `keyColumn` + `key`. |
| keyColumn | string | Column to search in. Mutually exclusive with `rowIndex`. |
| key | string\|number | Value to match in `keyColumn`. Required when `keyColumn` is specified. |
| column | string | Column to modify. |
| value | string\|number | New cell value. |
| expectedValue | string\|number | Optional. If set, the update is only applied if the cell currently has this value. |
## Return value
null
## Example
```json
modifyTableCell {"name": "MyTable", "rowIndex": 0, "column": "Price", "value": "9.99"}
```
---
## removeTableRows
Remove rows from a table.
## Parameter
Two different objects are used to either delete rows based on indices, or based on a search for a value in a column. To remove by index:
| Key | Type | Description |
| ----- | ------ | ------------------------------------------------------------------------------- |
| name | string | Table name. |
| index | number | Optional first row index, where the first rofw has index zero. Default is zero. |
| count | number | Number of rows to remove. |
To remove by seaching:
| Key | Type | Description |
| ------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| name | string | Table name. |
| column | string or number | An optional column to return, specified by either the header, or the column index. If not set then all columns will be returned. |
| value | string | Value to search for in the column. |
| single | boolean | If true, remove only the first match instead of all matching rows. |
## Return value
null
---
## renameTables
Rename one or more tables.
## Parameter
An object where the keys are existing table names, and the values are their new names.
## Return value
null
## Example
```json
renameTables {"Old Name": "New Name"}
```
---
## setTable
Create or replace a single table.
## Parameter
A [Table](/docs/json-objects/table) object with an additional `name` key:
| Key | Type | Description |
|------|--------|-----------------|
| name | string | The table name. |
See [setTables](./setTables) to create or replace several tables at once.
## Return value
| Key | Type | Description |
|-----|--------|------------------------------------|
| uid | string | Unique identifier of the table. |
## Example
```json
setTable {"name": "My Table", "headers": ["Code", "Name"], "rows": [["1", "One"]]}
```
---
## setTables
Create or replace one or more tables.
## Parameter
An object where the keys are table names, and the values are [Table](/docs/json-objects/table) objects.
## Return value
null
---
## deleteTimeFormat
Delete a time format.
## Parameter
The name of the time format to be removed.
## Return value
null
## Example
```json
deleteTimeFormat "My Time Format"
```
---
## getTimeFormat
Get a time format.
## Parameter
The name of the time format to get.
## Returns
A [Time format](/docs/json-objects/time-format) object.
## Example
```json
getTimeFormat "My Time Format"
```
---
## listTimeFormats
List all time formats.
## Parameter
None
## Returns
An object where the keys are time format names, and value values are [Time format](/docs/json-objects/time-format) objects. Each value also includes a `builtin` boolean indicating whether it is a built-in format.
## Example
```json
listTimeFormats
```
---
## setTimeFormats
Create or replace one or more time formats.
## Parameter
An object where the keys are time format names, and the values are [Time format](/docs/json-objects/time-format) objects.
## Return value
null
## Example
```json
setTimeFormats {"YY": {"format": "{YEAROFCENTURY}"}}
```
---
## deleteVariable
Delete a variable.
## Parameter
The name of the variable to be removed.
## Return value
null
## Example
```json
deleteVariable "My Variable"
```
---
## getVariable
Get a variable.
## Parameter
The name of the variable to get.
## Returns
A [Variable](/docs/json-objects/variable) object.
## Example
```json
getVariable "My Variable"
```
---
## listVariables
List all variables.
## Parameter
None
## Returns
An object where the keys are variable names, and value values are [Variable](/docs/json-objects/variable) objects.
## Example
```json
listVariables
```
---
## setVariables
Create or replace one or more variables.
## Parameter
An object where the keys are variable names, and the values are either strings or [Variable](/docs/json-objects/variable) objects.
## Return value
null
## Example
```json
setVariables {"VAR1": "Value 1", "VAR2": "Value 2"}
```
---
## disablePrintheadMaintenance
Disable the printhead maintenance mode.
## Parameter
| Key | Type | Description |
|---------|--------|-------------------------------------------------------------|
| printer | string | Printer ID. Required if more than one printer is available. |
## Return value
null
---
## enablePrintheadMaintenance
Enable the printhead maintenance mode.
## Parameter
| Key | Type | Description |
|---------|--------|-------------------------------------------------------------|
| printer | string | Printer ID. Required if more than one printer is available. |
| timeout | number | Optional timeout in seconds. |
## Return value
null
---
## marvin1:haltInkSystem
Halt the ink system. This will preform an emergency stop of the ink system, immediately stopping all pumps and closing all valves. It is not recommeded to use except in emergencies because it can make ink leak from the printhead the next time the ink system is started.
## Parameter
| Key | Type | Description |
|---------|--------|-------------------------------------------------------------|
| printer | string | Printer ID. Required if more than one printer is available. |
## Return value
null
---
## marvin1:enablePrintheadMaintenance
Enable the printhead maintenance mode on a Marvin1 printer, with control
over the maintenance mode and which printhead rows are affected.
## Parameter
| Key | Type | Description |
|---------|--------|--------------------------------------------------------------------------------------------------------------------|
| printer | string | Printer ID. Required if more than one printer is available. |
| mode | string | Optional. One of `DEFAULT`, `MANUAL_CLEANING`, `PRINT_PURGE`, or `FLOOD_PURGE`. Default `DEFAULT`. |
| rows | array of numbers | Optional. Zero-based printhead row indices to operate on (row mask). Defaults to all rows. |
| timeout | number | Optional timeout in seconds. |
## Return value
null
---
## marvin1:standbyInkSystem
Set the ink system to standby mode.
## Parameter
| Key | Type | Description |
|---------|--------|-------------------------------------------------------------|
| printer | string | Printer ID. Required if more than one printer is available. |
## Return value
null
---
## marvin1:startInkSystem
Start the ink system.
## Parameter
| Key | Type | Description |
|---------|--------|-------------------------------------------------------------|
| printer | string | Printer ID. Required if more than one printer is available. |
## Return value
null
---
## marvin1:stopInkSystem
Stop the ink system. Note that the printhead faceplate cover must be mounted to prevent ink from leaking from the printhead.
## Parameter
| Key | Type | Description |
|---------|--------|-------------------------------------------------------------|
| printer | string | Printer ID. Required if more than one printer is available. |
## Return value
null
---
## Version 4.0.x
Version 4.0.x introduced support for multiple printers in a single
controller, as well as support for multiple printer types. While all
requests will continue to work when the controller only has a single
NoLabel or Colorize printer configured, many requests require an extra
parameter when more than one printer is configured.
Several requests that are specific to s certain printer type have been
renamed. The old names are still supported, but are deprecated.
The settings object has also changed dramatically from earlier
versions.
## Renamed GPIO signals
All GPIO signals now require a prefix to indicate which equipment the
signal is connected to. The prefix is the eqiupment ID and a
period. The default eqipment ID is `MASTER`, so the output signal
`OUT1` must be specified as `MASTER.OUT1`.
## Renamed GPIO conditions
All GPIO conditions (except `always` and `never`) have been renamed to
support multiple printers. Assuming a printer ID of `NoLabel`, and an
equipment ID of `MASTER`, the conditions are renamed like this:
| Old name | New name |
|---------------------|-----------------------------------|
| `printer:ready` | `printer.Colorize.ready` |
| `printer:green` | `printer.Colorize.green` |
| `printer:amber` | `printer.Colorize.amber` |
| `printer:red` | `printer.Colorize.red` |
| `printer:ink:low` | `printer.Colorize.ink_low` |
| `printer:ink:empty` | `printer.Colorize.ink_empty` |
| `label:selected` | `printer.Colorize.label_selected` |
| `label:ready` | `printer.Colorize.label_ready` |
| `uv_light:on` | `printer.Colorize.uv_light1` |
| `uv_light:on` | `printer.Colorize.uv_light1` |
| `input:IN1` | `gpio.MASTER.IN1` |
## Printer specifier
All requests that directly affect a printer has a new parameter
`printer`. This parameters is **required** if more than one printer
is configured, but it is **strongly recommended** to always be set in
order to avoid problems if a new printer is added later.
The following requests now support a `printer` attribute:
- [getPrinterState](/docs/aurora-api/methods/Information/getPrinterState)
(was getState)
- [getPrinterStatus](/docs/aurora-api/methods/Information/getPrinterStatus)
(was getStatus)
- [waitForImage](/docs/aurora-api/methods/Images/waitForImage)
- [abortPrint](/docs/aurora-api/methods/Printing/abortPrint)
- [getCurrentPrintJob](/docs/aurora-api/methods/Printing/getCurrentPrintJob)
- [getPrintQueueLength](/docs/aurora-api/methods/Printing/getPrintQueueLength)
- [seekPrintQueueCheckpoint](/docs/aurora-api/methods/Printing/seekPrintQueueCheckpoint)
- [selectPrintJob](/docs/aurora-api/methods/Printing/selectPrintJob)
- [trigger](/docs/aurora-api/methods/Printing/trigger)
- [getPrinterSettings](/docs/aurora-api/methods/Settings/getPrinterSettings)
- [setPrinterSettings](/docs/aurora-api/methods/Settings/setPrinterSettings)
## Renamed requests
| Old name | New name |
|-----------------------------|-----------------------------------------------------------------------------------------------------|
| getSettings | [getPrinterSettings](/docs/aurora-api/methods/Settings/getPrinterSettings) |
| setSettings | [setPrinterSettings](/docs/aurora-api/methods/Settings/setPrinterSettings) |
| disablePrintheadMaintenance | [marvin1:disablePrintheadMaintenance](/docs/aurora-api/methods/marvin1/disablePrintheadMaintenance) |
| enablePrintheadMaintenance | [marvin1:enablePrintheadMaintenance](/docs/aurora-api/methods/marvin1/enablePrintheadMaintenance) |
| haltInkSystem | [marvin1:haltInkSystem](/docs/aurora-api/methods/marvin1/haltInkSystem) |
| standbyInkSystem | [marvin1:standbyInkSystem](/docs/aurora-api/methods/marvin1/standbyInkSystem) |
| startInkSystem | [marvin1:startInkSystem](/docs/aurora-api/methods/marvin1/startInkSystem) |
| stopInkSystem | [marvin1:stopInkSystem](/docs/aurora-api/methods/marvin1/stopInkSystem) |
## New requests
- [getSpeedInfo](/docs/aurora-api/methods/Information/getSpeedInfo)
- TBD
---
## Import(Methods)
### import
Imports an [import JSON object](../../../json-objects/import).
#### Returns
A JSON object containing information about what was successfully imported.
#### Examples
Import a variable and a label:
```json
{
"jsonrpc": "2.0",
"method": "import",
"params": {
"variables": {
"My Variable": {
"value": "My Value"
}
},
"labels": {
"My Label": {
"metric": true,
"height": 108,
"width": 200,
"objs": [
{
"type": "Rect",
"x": 55,
"y": 38,
"height": 30,
"width": 30,
"fillColor": "black"
},
{
"type": "Text",
"x": 0,
"y": 0,
"text": "Hello {VARIABLE;My Variable}",
"color": "black",
"font": {
"family": "Liberation Sans",
"style": "Regular",
"height": 20
}
}
]
}
}
}
}
```
Returns:
```json
{"id":null,"jsonrpc":"2.0","result":{"labels":["My Label"],"variables":["My Variable"]}}
```
---
## Label management
See also the [Import](./import) section to set label in the printer.
### deleteLabel
Delete a label.
| Parameter | Type | Description |
| --------- | ------ | ---------------------- |
| name | string | The name of the label. |
#### Returns
null
#### Example
```json
{"jsonrpc": "2.0", "method": "deleteLabel", "params": {"name": "My Label"}}
```
### getLabel
Get a label.
| Parameter | Type | Description |
| --------- | ------ | ---------------------- |
| name | string | The name of the label. |
#### Returns
A label. See the Aurora Label Specification.
#### Example
```json
{"jsonrpc": "2.0", "method": "getLabel", "params": {"name": "My Label"}}
```
---
## Print job selection
### selectPrintJob
The selectPrintJob method is a very powerful method that allows control of what to print. The simplest form deselects any existing jobs, or selects a single label, but it can also set up a database driven job. The job can either replace the existing job, or add it to a queue.
The content is described in [Print job](../../../json-objects/print-job).
#### Returns
null
#### Examples
Deselect all print jobs (clearing the queue):
```json
{"jsonrpc": "2.0", "method": "selectPrintJob", "params": {}}
```
Select a single label "MyLabel":
```json
{"jsonrpc": "2.0", "method": "selectPrintJob", "params": {"labelName": "MyLabel"}}
```
Select a single label "MyLabel", limit to a single print, and add to the end of the queue:
```json
{
"jsonrpc": "2.0",
"method": "selectPrintJob",
"params": {"labelName": "MyLabel", "copies": 1, "queue": true}
}
```
Search the table "MyTable" in the column "Product" for "MyProduct", and select the label from the column "Label":
```json
{
"jsonrpc": "2.0",
"method": "selectPrintJob",
"params": {
"tableName": "MyTable",
"keyColumn": "Product",
"key": "MyProduct",
"labelColumn": "Label"
}
}
```