Version 3.2

Startup and diagnostic functions

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.

Pallet pattern functions

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

Key-value storage

These functions are used to store variables that should keep their values between UR program runs. Each pallet manager instance can have its own key-value storage, there is also a static storage available for all instances.

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.

Name	read_key_value_static
Signature	<type> read_key_value_stati(string attribute_name)
Remarks	This is the static version of read_key_value.

Name	write_key_value_static
Signature	<type> write_key_value_static(int instance, string attribute_name, <type> attribute_value)
Remarks	This is the static version of write_key_value.

Instance management functions

The pallet manager daemon can simultaneously handle multiple data structures, called instances, which reflect the loaded pattern and the pallet completion state. This feature is only used in Dual Product mode, where both the left and right pallet have their own patterns and pallet completion states. All functions related to the pallet state require the instance number as an input parameter. Instance number should be 0 by default.

Name	get_instances
Signature	int[] get_instances()
Description	Returns the array of instance identifiers.
Parameters
Return value	On success, the function returns the following array: [nr_instances, instance1, instance2, …] where instanceX is the numerical identifier of a pallet manager instance (see the instance parameter of various functions) On failure, the function returns [0]

Name	delete_instance
Signature	bool delete_instances(int instance)
Description	Deletes the given pallet manager instance and all its data from memory. The currently loaded JSON as well as the entire key-value storage will be completely unloaded and is no longer available for subsequent function calls.
Parameters	instance: pallet manager instance to be used
Return value	On success, the function returns true. On failure, the function returns false.

Functions related to collision testing

Name	get_shadow_points
Signature	double[] get_shadow_points(int instance, int direction, int nr_layer)
Description	Calculates and returns a list of x,y coordinate pairs that define the corners of the collision area, seen from the given direction.
Parameters	instance: pallet manager instance to be used direction: expected arrival direction of the new box(es). 1 if the collision area should be seen from north-west, -1 if seen from north-east. nr_layer: layer to be checked
Return value	The corner points of the collision area, seen from the given direction.

Name	is_task_in_shadow
Signature	bool is_task_in_shadow(int instance, int direction)
Description	Determines the current task collision state, assuming that the box(es) arrive from the given direction.
Parameters	instance: pallet manager instance to be used direction: expected arrival direction of the new box(es). 1 if the collision area should be seen from north-west, -1 if seen from north-east.
Return value	True if the current task is located in a pallet area that cannot be reached with linear motion in the given direction without collision, false otherwise.

Order management functions

Orders consist of one or more full or partial pallets of the same product type. The following functions are used for manipulating orders.

Name	get_nr_orders
Signature	int get_nr_orders(int instance)
Description	Counts the total number of orders in the specified instance. Each order can have one or more full or partial pallets of the same product type.
Parameters	instance: pallet manager instance to be used
Return value	Number of orders.
Remarks	This function does not count the total number of pallets.

Name	get_order_id
Signature	int get_order_id(int instance, int order_number)
Description	Gives the unique ID of the order pointed by order_number.
Parameters	instance: pallet manager instance to be used order_number: a number between 0 and nr_orders-1 that depends on the total number of orders.
Return value	Order ID of the specified order.
Remarks	Order ID is not used by the system, but can be freely used as a foreign key reference to external systems such as ERP.

Name	get_order_description
Signature	string get_order_description(int instance, int order_number)
Description	Gives the description of the order pointed by order_number.
Parameters	instance: pallet manager instance to be used order_number: a number between 0 and nr_orders-1 that depends on the total number of orders.
Return value	Description of the specified order.
Remarks	Currently not used by the system. The description field can contain any text for Operator convenience.

Name	get_order_pattern_name
Signature	string get_order_pattern_name(int instance, int order_number)
Description	Gives the name of the pattern json file to be loaded (without ".json" suffix)
Parameters	instance: pallet manager instance to be used order_number: a number between 0 and nr_orders-1 that depends on the total number of orders.
Return value	Name of the pattern json file to be loaded during palletizing the specified order.
Remarks

Name	get_order_loads
Signature	int[] get_order_loads(int instance, int order_number)
Description	Gives the requested number of products on each pallet of the specified order.
Parameters	instance: pallet manager instance to be used order_number: a number between 0 and nr_orders-1 that depends on the total number of orders.
Return value	An array of integers that should be interpreted as follows: element 0: the number of pallets to be done elements 1…number of pallets: the number of products on the N-th. pallet
Remarks	When the number of products is set to 0 it means a full pallet.

Name	insert_order
Signature	bool insert_order(int instance, int order_number, int order_id, string order_description, string pattern_name, int[] loads)
Description	Creates a new order and inserts it into the list of existing orders at the specified position.
Parameters	instance: pallet manager instance to be used order_number: a number between 0 and nr_orders-1 that depends on the total number of orders order_id: order ID that can be used as a foreign key in external systems order_description: description for the operator pattern_name: name of the pattern json file to be loaded loads: an array of integers that should be interpreted as follows: element 0: the number of pallets to be done elements 1…number of pallets: the number of products on the N-th. pallet
Return value	true if successful, otherwise false
Remarks	Orders that follow the newly inserted order will get a new order_number.

Name	update_order
Signature	bool update_order(int instance, int order_number, int[] loads)
Description	Updates loads of the specified order. Typical use is after completing a pallet. (Set nr. pallets = nr. pallets -1, and remove the first element from the list)
Parameters	instance: pallet manager instance to be used order_number: a number between 0 and nr_orders-1 that depends on the total number of orders loads: an array of integers that should be interpreted as follows: element 0: the number of pallets to be done elements 1…number of pallets: the number of products on the N-th. pallet
Return value	true if successful, otherwise false
Remarks	This function is being used for updating the remaining loads after a pallet has been completed. It is currently not possible to update the order id, description, and pattern name once the order has been created,

Name	delete_order
Signature	bool delete_order(int instance, int order_number)
Description	Remove the specified order from the order list. Typical use of this function is when all pallets of the specified order are completed and the 'empty' order can be safely deleted.
Parameters	instance: pallet manager instance to be used order_number: a number between 0 and nr_orders-1 that depends on the total number of orders
Return value	true if successful, otherwise false
Remarks

Name	clear_orders
Signature	bool clear_orders(int instance)
Description	Deletes all orders regardless of their completion state. The order list becomes empty.
Parameters	instance: pallet manager instance to be used
Return value	true if successful, otherwise false
Remarks

Name	load_orders
Signature	bool load_orders(int instance, string file_name)
Description	Clears all existing orders and loads orders from the specified json file.
Parameters	instance: pallet manager instance to be used file_name: name of the file (without .json suffix) that contains the order definitions. The file must be located in the working directory of the pallet manager daemon.
Return value	true if successful, otherwise false
Remarks	TODO add example file here!

Name	load_orders_from_string
Signature	bool load_orders_from_string(int instance, string order_defs)
Description	Clears all existing orders and loads orders from the specified string that must be a valid json.
Parameters	instance: pallet manager instance to be used order_defs: a string that contains a valid json with order definitions
Return value	true if successful, otherwise false
Remarks

Offline storage functions

Offline storage functions provide access to persistent data in special json files.

Name	open_database
Signature	bool open_database(int instance, string db_name, bool read_only)
Description	Reads all json files into memory from the given subfolder specified by db_name.
Parameters	instance: pallet manager instance to be used db_name: name of the database, technically this is a subfolder in the working directory read_only: if true, existing json files are opened in read-only mode, and no new files can be created
Return value	true if successful, otherwise false
Remarks

Name	write_database
Signature	bool write_database(int instance)
Description	Writes all json files into the currently selected subfolder from memory.
Parameters	instance: pallet manager instance to be used
Return value	true if successful, otherwise false
Remarks	If the database was open in read-only mode, no write operations are performed and the function returns true immediately.

Name	close_database
Signature	bool close_database(int instance)
Description	Writes all json files into the currently selected subfolder from memory, and then releases all memory.
Parameters	instance: pallet manager instance to be used
Return value	true if successful, otherwise false
Remarks	If the database was open in read-only mode, no write operations are performed, but the working memory is being released anyway.

Name	drop_database
Signature	bool drop_database(int instance, string db_name)
Description	Deletes the specified subfolder completely.
Parameters	instance: pallet manager instance to be used db_name: name of the database, technically this is a subfolder in the working directory
Return value	true if successful, otherwise false
Remarks	If the specified subfolder was currently opened as the active database, a close_database is being called automatically prior to deletion.

Name	read_table
Signature	<type> read_table(int instance, string table_name, string key)
Description	Reads the value specified by key in the given table. Technically the table is a json file and the key is the json attribute in the file.
Parameters	instance: pallet manager instance to be used table_name: name of the table "file" in the currently selected subfolder key: what to read from the json structure.
Return value	the value of the json attribute
Remarks	Return type <type> depends on what has been read. (int, string, array, …)

Name	write_table
Signature	<type> write_table(int instance, string table_name, string key, <type> value)
Description	Writes the value of a json attribute 'key' in table 'table_name'. Technically the table is a json file and the key is the json attribute in the file.
Parameters	instance: pallet manager instance to be used table_name: name of the table "file" in the currently selected subfolder key: what to write in the json structure value: the value of the json attribute to be stored (int, string, array, …)
Return value	same as the input parameter 'value' was
Remarks	Return type <type> depends on what has been written. (int, string, array, …)

Other functions

These functions are provided for general purposes.

Name	substring
Signature	string substring(string source, int start_pos=0, int nr_characters=length)
Description	Returns the given substring of a source string.
Parameters	source: the source string start_pos: 0-based start position of the new string in the source string nr_characters: the length of the new string
Return value	The newly created string.

Name	concat
Signature	string concat(bool/int/double/string a, bool/int/double/string b, ...)
Description	All input values are converted to strings, and then concatenated.
Parameters	a, b, ...: input value to be written into the resulting string.
Return value	The newly created string.
Remarks	The literal "\n" is replaced with the newline character 0x10, allowing the programmer to create a multi-line text.

Pally Knowledge Base

Pallet Manager daemon Reference Manual