Name

ping

Signature

bool ping()

Description

Test function. Always returns true.

Parameters

Return value

true

Name

set_working_dir

Signature

bool set_working_dir(string dir)

Description

Sets the working directory from where the pallet manager loads json files, and where the backup file is created.

Parameters

dir: the full path of the working directory to be used

Return value

true on success, false on error.

Name

get_md5sum

Signature

string get_md5sum(string product_name)

Description

Calculates and returns the md5sum checksum for the specified file (name without the .json suffix)

Parameters

product_name: the box type to be palletized, e.g. C000272

Return value

This function can be used to verify the integrity of a file. The checksum will be different after modifications.

Name

load

Signature

bool load(int instance, string product_name)

Description

Loads the pattern definition from {product_name}.json and the zone definition from {product_name}.zones.json or the default zone definition from zones.json file.

Case insensitivity is implemented for some degree: full uppercase and full lowercase file names are also searched for.

Parameters

instance: pallet manager instance to be used

product_name: the box type to be palletized, e.g. C000272

Return value

true on success, false on error

Name

build_layers

Signature

bool build_layers(int instance, int selected_pattern)

Description

Builds the empty pallet completion state based on the pattern or the altPattern structures of each layer type.

This function is used to handle different layout definitions for the left pallet.

Parameters

instance: pallet manager instance to be used

selected_pattern: should be 1 to build the pallet completion state from the "pattern" structures, 2 for the "altPattern"

Return value

true on success, false on error

Name

set_nr_products

Signature

bool set_nr_products(int instance, int nr_products)

Description

Creates a partial pallet with the specified number of boxes. This function can be used after load() only.

Depending on the number of boxes, the algorithm creates n complete layers, or n-1 complete and one partial layer.

Parameters

instance: pallet manager instance to be used

nr_products: the exact number (or maximum number) of boxes to be palletized.

Return value

true on success, false on error.

Name

partial_palletize

Signature

bool partial_palletize(int instance, int layer_nr, int box_nr)

Description

Creates a partial pallet by specifying the layer number and the box number on the given layer where the program should continue palletizing.

Parameters

instance: pallet manager instance to be used

layer_nr: the layer number where the next task will be performed

box_nr: the box position on the specified layer where the next task will be performed

Return value

[current box position, current zone, previous zone]

Name

get_pallet_dimensions

Signature

double[] get_pallet_dimensions(int instance)

Description

Returns the pallet dimensions [width, length, height] in millimeters as specified in the currently loaded product json file.

Parameters

instance: pallet manager instance to be used

Return value

On success, the function returns [width, length, height] in an array. On failure, the return value is [0, 0, 0]

Name

get_product_dimensions

Signature

double[] get_product_dimensions(int instance)

Description

Returns the box dimensions (width, length, height) in millimeters as specified in the currently loaded product json file WITHOUT PADDING, product weight in gramms, and label orientation in degrees (90: right, -90: left, 0: front) related to the box face.

Parameters

instance: pallet manager instance to be used

Return value

On success, the function returns [width, length, height, weight, label_orientation] as an array. On failure, the return value is [0, 0, 0, 0, 0]

Name

get_nr_zones

Signature

int get_nr_zones(int instance)

Description

Returns the total number of zones defined in the currently loaded (either product-specific or generic) zone file.

Parameters

instance: pallet manager instance to be used

Return value

On success, the function returns the total number of zones (including empty zones). On failure, the function returns 0.

Name

get_zone_app_data

Signature

string get_zone_app_data(int instance, int nr_zone)

Description

Returns the value of the "appData" field for the specified zone as defined in the currently loaded zones file.

The appData is not used by the pallet manager itself, but it can contain extra information for the main application.

Parameters

instance: pallet manager instance to be used

nr_zone: 0-based index of zone. For zone order, see the zones.json file.

Return value

On success, the function returns the appData field. On failure, the function returns an empty string.

Name

get_zone_pos_data

Signature

number[] get_zone_pos_data(int instance, int nr_zone)

Description

Returns the value of "posData" field for the specified zone as defined in the currently loaded zones file.

The posData is not used by the pallet manager itself, but it can contain extra information for the main application. The elements of posData define X, Y, and Z position offsets for the robot base position in the physical world. Lifting column position, for example, can be represented in posData[2].

Parameters

instance: pallet manager instance to be used

nr_zone: 0-based index of zone. For zone order, see the zones.json file.

Return value

On success, the function returns the posData field as an array of [x, y. z]. On failure, the function returns an empty array.

Remarks

posData has been made optional in Pally 2.9 and therefore the return value can be empty also in normal circumstances.

Name

get_next_task

Signature

number[] get_next_task(int instance, int nr_boxes, int nr_zone)

Description

The function finds and returns the position, orientation, and payload weight of the next palletizing task to be performed.

The function marks the selected box position(s) as "reserved" until a commit_task or a cancel_task is performed.

In case there is a previous get_next_task in progress, which has not yet been committed or cancelled, a cancel_task() is automatically performed before finding the new task.

Parameters

instance: pallet manager instance to be used

nr_boxes: the number of boxes available on the conveyor

nr_zone: the 0-based index of the currently selected zone

Return value

On success, the function returns the following array:

[int layer, int nr_boxes, double X, double Y, double Z, int rotations, int weight, int taskType, int gripperRotations, int approach, double width, double length, double height]

Where

layer: the 0-based layer index

nr_boxes: the number of boxes to be lifted, <= nr_boxes available on conveyor. If there are no more boxes to be palletized in the specified zone, the nr_boxes is zero.

X: center point of the payload (mm) in the logical pallet coordinate system

Y: center point of the payload (mm) in the logical pallet coordinate system

Z: top surface of the payload (mm) measured from the empty pallet surface

rotations: bitmask of allowed rotations

Bit 0: 0° rotation is allowed by the pattern

Bit 1: 90° (clockwise) rotation is allowed

Bit 2: 180° (aka. -180°) rotation is allowed

Bit 3: 270° (aka. -90°) rotation is allowed

weight: total weight of payload (box weight * number of boxes) in gramm

taskType: 1 for box, 2 for shim paper

gripperRotation: bitmask of allowed gripper rotations at pickup

Bit 0: 0° rotation is allowed

Bit 1: 90° (clockwise) rotation is allowed

Bit 2: 180° (aka. -180°) rotation is allowed

Bit 3: 270° (aka. -90°) rotation is allowed

approach: 1 for normal, -1 for inverse approach

width, length, height: the dimensions of the payload. For shim papers, it's pallet width, pallet length, and shim paper height. For normal boxes, box width, nr_products * box length, and box height are returned.

On failure, the function returns an array of zeros.

Name

commit_task

Signature

bool commit_task(int instance)

Description

Sets the "reserved" pattern positions' state to "done". The commit_task function should be executed when a pending task (returned by get_next_task) has been successfully palletized and no error occurred.

Parameters

instance: pallet manager instance to be used

Return value

true on success, false on error.

Name

cancel_task

Signature

bool cancel_task(int instance)

Description

Sets the "reserved" pattern positions to "empty". The cancel_task function should be executed when a pending task (returned by get_next_task) has not been successfully palletized, either because of a program stop or a hardware failure.

Parameters

instance: pallet manager instance to be used

Return value

true on success, false on error.

Name

get_next_depal_task

Signature

number[] get_next_depal_task(int instance, int nr_boxes, int nr_zone)

Remarks

This is the reverse version of get_next_task that starts searching the first positions with "done" state in the backward direction. Should be used when building the pallet down (de-palletizing).

Name

commit_depal_task

Signature

bool commit_depal_task(int instance)

Remarks

This is the reverse function of commit_task that sets the "reserved" pattern positions' state to "empty". Should be used when building the pallet down (de-palletizing).

Name

cancel_depal_task

Signature

bool cancel_depal_task(int instance)

Remarks

This is the reverse function of cancel_task that sets the "reserved" pattern positions' state to "done". Should be used when building the pallet down (de-palletizing).

Name

reset_pallet_state

Signature

bool reset_pallet_state(int instance)

Description

Sets the pattern position state to "empty" for all positions of the pallet. This is equivalent to reloading the same JSON again, assuming the JSON has not been changed.

Parameters

instance: pallet manager instance to be used

Return value

true on success, false on error.

Name

get_pallet_state

Signature

int[] get_pallet_state(int instance)

Description

Returns the number of total, done, and remaining boxes.

Parameters

instance: pallet manager instance to be used

Return value

On success, the function returns the array:

[nr_total, nr_done, nr_empty] where

nr_total: the total number of boxes (pattern positions) specified in the currently loaded json file

nr_done: number of boxes that have been already palletized successfully (with commit_task)

nr_empty: number of empty box positions in the currently loaded json file.

On error, the function returns [0, 0, 0]

Remarks

It is possible to have nr_done + nr_empty < nr_boxes when a get_next_task exists without commit/cancel.

Name

get_pattern_info

Signature

int[] get_pattern_info(int instance)

Description

Returns detailed information about the currently loaded pattern.

Parameters

instance: pallet manager instance to be used

Return value

On success, the function returns the array:

[nr_layers, nr_product_1, nr_product_2, ...] where

nr_total: the total number of layers in the currently loaded json file

nr_product_X: number of boxes on the specified layer (bottom-up)

On error, the function returns [0, 0]

Name

backup

Signature

bool backup(int instance)

Description

Writes the current pallet state into palbak.json in the working directory. The backup file contains the name of the currently loaded product type, and the internal state (empty=0, reserved=1, done=2) for each pattern position.

Parameters

instance: pallet manager instance to be used

Return value

On success, the function returns true. On error, the return value is false.

Name

restore

Signature

bool restore(int instance)

Description

Loads the palbak.json file that has been saved by the backup() function. If succeeded, it loads the product-specific json file and the product-specific (or generic) zones json file, and updates the internal state of each pattern position.

As a side-effect, the backup/restore mechanism can be used to dynamically change the pallet layout during palletizing, as long as the number of boxes remain the same.

Parameters

instance: pallet manager instance to be used

Return value

On success, the function returns true. On error, the return value is false.

Name

init_pattern_cache

Signature

int init_pattern_cache()

Description

The pallet manager scans the working directory for JSON files and collects information from them. All information is stored in an array, which can be accessed by the following functions:

get_file_name

get_pattern_name

get_formatted_info

Parameters

-

Return value

On success, the function returns the number of JSON files found in the working directory. On error, the return value is 0.

Name

get_file_name

Signature

string get_file_name(int index)

Description

Returns the file name of the JSON file with the given index. The index must be between 0 and the value returned by init_pattern_cache().

This function can only be used after a successful call to init_pattern_cache().

Parameters

index: array index in the pattern cache

Return value

On success, the function returns the file name. On error, the return value is an empty string.

Name

get_pattern_name

Signature

string get_pattern_name(int index)

Description

Returns the "name" field of the JSON file with the given index. The index must be between 0 and the value returned by init_pattern_cache().

This function can only be used after a successful call to init_pattern_cache().

Parameters

index: array index in the pattern cache

Return value

On success, the function returns the "name" field in the JSON. On error, the return value is an empty string.

Name

get_formatted_info

Signature

string get_formatted_info(int index)

Description

Returns an overview of the JSON file with the given index as a short JSON. The index must be between 0 and the value returned by init_pattern_cache().

This function can only be used after a successful call to init_pattern_cache().

Parameters

index: array index in the pattern cache

Return value

The return value is always a JSON with the following format:

{"totalHeight":%g,"totalWeight":%g,"boxCount":%d,"layerCount":%d,"boxWidth":%g,"boxLength":%g,"boxHeight":%g,"boxWeight":%u,"dateModified":"%s","description":"%s","maxGrip":"%u","layerBoxCount":[%s]}

On success, all fields contain the respective information from the source JSON. On failure, the fields are set to zero, and the description is "failed to load".

Name

get_formatted_pallet_state

Signature

string get_formatted_pallet_state(int instance)

Description

Returns an overview of the currently loaded pallet in as a short JSON.

Parameters

instance: pallet manager instance to be used

Return value

The return value is always a JSON with the following format:

{"patternName":"%s","currentPalletId":%d,"softPalletReadyOk1":%d,"softPalletReadyOk2":%d,"totalBoxesCount":%d,"totalLayersCount":%d,"totalBoxesProgress":%d,"layersProgress":%d,"boxCountPerLayer":%d,"currentLayerBoxProgress":%d,"description":"%s"}

Name

init_zones_generator

Signature

bool init_zones_generator(bool continuous, int max_stroke)

Description

Initializes the automatic zones generator for a specific lifting column.

By default, the zones generator generates only one dummy zone

Parameters

continuous: true if the lifting column can be moved to any intermediate position

max_stroke: maximum stroke in millimeters

Return value

true on success, false on error

Name

init_key_value

Signature

<type> init_key_value(int instance, string attribute_name, <type> attribute_value)

Description

Creates an entry in the key-value storage with the given attribute name and attribute value, but only if it does not exist yet.

Parameters

instance: pallet manager instance to be used

attribute_name: name of the attribute to be created

attribute_name: initial value of the new attribute

Return value

The existing value of the given attribute, if it exists.

atttibute_value, if the attribute is newly created.

Remarks

<type> can be any data type that is supported by the URScript

Name

read_key_value

Signature

<type> read_key_value(int instance, string attribute_name)

Description

Returns the value of the attribute from the key-value storage.

Parameters

instance: pallet manager instance to be used

attribute_name: name of the attribute to be read

Return value

The existing value of the given attribute, if it exists.

Remarks

<type> can be any data type that is supported by the URScript

Name

write_key_value

Signature

<type> write_key_value(int instance, string attribute_name, <type> attribute_value)

Description

Creates or updates an entry in the key-value storage with the given attribute name and attribute value.

Parameters

instance: pallet manager instance to be used

attribute_name: name of the attribute to be created

attribute_name: initial value of the new attribute

Return value

On success, the function returns attribute_value. On failure, the function returns false.

Remarks

<type> can be any data type that is supported by the URScript

Name

init_key_value_static

Signature

<type> init_key_value_static(string attribute_name, <type> attribute_value)

Remarks

This is the static version of init_key_value that does not require an instance nr.