Yaskawa Install Package (YIP / .yip) files allow combining a number of components into a single convenient file for distribution to an end-user for installation together—such as robot INFORM jobs, Tool property presets, I/O names, Smart Pendant Extensions, MotoPlus controller apps and other items.
While packages can be created using the Smart Packager desktop application, it is sometimes useful to be able to automate package creation. For example, developers of a Smart Pendant Extension app may wish to automate packaging their extension as part of their build process. This can be achieved using the command-line interface for Smart Packager.
Package meta-data JSONNET overview
Package global properties
Conditional Installation
Installation Prompts
Components:
The process of creating a package involves invoking the Smart Packager from the shell command-line and supplying a folder containing and artifacts that should be included in the package (e.g. job files, a folder of extension related files, etc.); a Jsonnet ("jay sonnet") template detailing the package meta-data (package-wide information, dependencies, pre-requisites; entries for each component to be installed and the details of each) - all of which is described below. Optionally, a signing private key can be provided such that the resulting package .yip file can only be opened or edited by providing that key.
The following assumes you are using the bash shell under Linux (e.g. Ubuntu). Using Windows WSL2 bash should be identical.
(Use from Windows via a Command Prompt is not well tested or supported, but may function with approriate adjustements to path seperators).
You can obtain a summary of the command-line options by passing --help:
$ ./SmartPackager --help
Usage: ./SmartPackager [options]
Yaskawa Smart Packager 1.3
Options:
-h, --help Displays help on commandline options.
--help-all Displays help including Qt specific options.
--version Display version.
--key <keyfile> Your Vendor Private key.
--akey <keyfile> Authorization Private key (if different from
key).
--newkey <keyfile> Change package to use new key (or
'unprotected')
--packages <folder> List packages.
--json <componentname> Show JSON metadata (component canonical name
for specific component, otherwize ".").
--edit Interactively edit JSON metadata (with system
editor).
--package <packagefile> Package file (.yip).
--new <packagejsonheaderfile> New package from template (json file).
--unprotected Create new package as unprotected (editable by
everyone) - no vendor key required.
--archive <archivefolder> Package archive folder.
--vars <variables> Package template variables
(name1=value1,name2=value2,..).
--add <componentfile> Add Installable Component (json file).
--remove <componentname> Remove Installable Component (canonical name).
--info <packagefile> Show package information.
--exportpubkey Export public key from specified (--key)
vendor private key.
--exportpubkeyhash Export SHA512 hash of public key from
specified (--key) vendor private key.
The meta-data of a package is represented in JSON format. For example, to see the meta-data for a package (one that isn't protected by a vendor key), such as calculator-1_0.yip, you can invoke:
$ ./SmartPackager --package calculator-1_0.yip --json .
The --package specifies the package .yip file to query; the --json indicates to output the JSON metadata and specifically . asks for everything (rather than a specific component). You'd see something like the following (- some long strings have been elided for brevity below - such as the inline Base64-encoded logo image data).
{
"archiveHash": "81...6B",
"archiveKey": "4B...DE",
"authorName": "Yaskawa Innovation Inc.",
"canonicalName": "com.yaskawa.yii.calculator",
"components": [
{
"canonicalName": "com.yaskawa.yii.calculator.ext",
"componentVersion": {
"nmajor": 1,
"nminor": 0,
"npatch": 0,
"v": "1.0.0"
},
"conflictDefaultAction": "overwrite",
"conflictOption": "default",
"description": "Calculator",
"extension": {
"configuration": {
},
"displayNames": {
"en": "Calculator",
"ja": "電卓"
},
"executableFile": "Calculator.jar",
"extFolder": ".",
"extensionDependencies": {
},
"iconName": "",
"keepFilesOnUpdate": false,
"requireAPIVersion": {
"nmajor": 2,
"nminor": 0,
"npatch": 3,
"v": "2.0.3"
},
"requiredPlatform": "any",
"requiredRuntime": "openjdk11",
"supportedLanguages": [
"en"
],
"version": 2
},
"metadata": {
},
"modifiesController": false,
"skipWithoutController": false,
"type": "extension",
"version": 2
}
],
"contactEmail": "david.jung@yaskawainnovation.com",
"created": "2020-12-14 18:37:25",
"descriptions": {
"en": "Simple calculator utility"
},
"displayNames": {
"en": "Calculator",
"ja": "電卓"
},
"includesArchive": true,
"installationExpiry": "2262-04-11",
"metadata": {
"allow_reinstall": "true",
"vendorIconDataURI": "data:image/png;base64,iVBORw0KGgoAAA...5CYII="
},
"packageVersion": {
"nmajor": 1,
"nminor": 0,
"npatch": 0,
"v": "1.0.0"
},
"requireControllerConnected": false,
"salt": "mpT...8nz",
"signature": "21B...89",
"suggestControllerBackup": false,
"supportedLanguages": [
"en",
"ja"
],
"type": "",
"vendor": "Yaskawa",
"vendorIcon": "images/Yaskawa-Y-logo.png",
"vendorRSAPublicKeyHex": "3082...111",
"version": 2
}
Many of these fields are automatially generated.
While a package's meta-data is stored in JSON format in the .yip file, for automating package creation, it is more convenient to write and maintain a JSONNET template file - which is similar to JSON, but with some enhancements to make it easier and more convenient for people to edit.
Here is the .jsonnet template file for the Calculator example extension package, as found on the Extension SDK. .jsonnet files should contain UTF-8 encoded Unicode (of which 'plain' ASCII text is a subset).
// Template for Calculator YIP file meta-data
{
version: 2, // file format version
// globally unique id for package
canonicalName: "com.yaskawa.yii.calculator",
vendor: "Yaskawa",
vendorIcon: "images/Yaskawa-Y-logo.png", // company logo
packageVersion: { v: "1.0.0" },
type: "extension",
supportedLanguages: ["en", "ja"],
displayNames: {
"en": "Calculator",
"ja": "電卓"
},
descriptions: {
"en": "Simple calculator utility"
},
authorName: "Yaskawa Innovation Inc.",
includesArchive: true,
installationOverridePasscode: "123456",
metadata: {
// when developing & testing, it is useful to be able to reinstall
// the same version repeatedly over itself.
// Leave false for production release
allow_reinstall: 'true'
},
requireControllerConnected: false,
suggestControllerBackup: false,
components: [
{
version: 2,
// globally unique id for extension - must match Java Extension() constructor
canonicalName: "com.yaskawa.yii.calculator.ext",
type: "extension",
description: "Calculator",
modifiesController: false,
skipWithoutController: false,
extension: {
version: 2,
requireAPIVersion: { v:"2.0.4" },
supportedLanguages: ["en"],
displayNames: {
"en": "Calculator",
"ja": "電卓"
},
iconName: "images/calculator_icon-64.png", // extension icon
requiredPlatform: "any",
requiredRuntime: "openjdk11",
requireNetworking: false,
keepFilesOnUpdate: false,
extFolder: '.',
executableFile: "Calculator.jar",
configuration: {}
}
}
]
}
As you can see, there are properties global to the package (those with a single indent within the outermost { and }) and a list ([]) of Components. Each Component is of a particular type and roughly correspond to the kind of artifacts that can be included in a package (for example, there is a JobsComponent, IONamesComponent, ExtensionComponent and several others).
Key features of the Jsonnet format that differ from JSON are:
//)See the official Jsonnet web-site for details.
The following properties (JSON/Jsonnet fields) represent package-wide information.
For each, the name, kind or type of value (e.g. integer/number, a quoted string, or a boolean true or false, for example) and an indication if it is optional or has a default value when omitted, is given.
canonicalName (string) - a unique machine-readable identifier to refer to the package
Since the display name varies across languages, the software needs a unique machine-readable identifier to refer to the package, so, for example, it can identify different versions of the same package. This unique identifier is termed the "canonical name" and must be globally unique across all vendors for all time. The recommended format is lowercase words separated by dots, similar to a web domain address, but with the components reversed (similar to Java package names). For example, com.acme.grippers.zx9000.ext, com.acme.grippers.jobs.v2. It is not shown to end-users (though may appear in log output). You should keep the package canonical name consistent as you release newer versions, so that the installer will know that newer versions should replace any existing versions installed rather than being installed alongside them. Hence, the package is uniquely identified by the combinatin of the canonicalName and the packageVersion.
packageVersion (map; v key required) - The version of this package. (Contained components can have their own independent version, or inherit this one)
Assigning a version number to your package allows the installer to understand if the package is already installed, or if an older version is installed and can be updated to a newer one, etc. The format follows the Semantic Versioning standard (see semver.org) or 'MAJOR'.'MINOR'.'PATCH'. For example, "1.0.0". Note that the elements increase numerically independently, so "1.9.0" is a lower verson than "1.10.0" since 9 is smaller than 10. The version can optionally include a 'release' part - e.g. "0.1.0-dev" and build tag, such as "0.1.0-dev+123". The value is a map (JSON object) with a "v" key (for historical reasons) - for example { v: "1.0.0" }
NOTE: Special treatment of pre-release development versions
If the release part is "-dev" or "-pre", the installer considers the package a pre-release. In this case, it will not allow it to be installed unless the user has "Development Access" and can provide the 'Install Override Passcode' (see below). Using a pre-release tag is advised during development and testing, so that if a pre-release version should inadvertantly be distributed, it cannot normally be installed.
type (string; optional; one of "" (empty string, default) or "extension") - If the package contains at least one "extension" type Component, this must be the string "extension", otherwise the empty string.
version (int; optional, default 1) - this is the version of the package meta-data format itself (not the specific package). The current version is 3.
Not to be confused with the version of the specific package being created. The format version may be incremented by Yaskawa when the format is changed. However, most format chages involve the addition of new optional properties with sensible defaults for backward compatibility.
supportedLanguages (list of strings) - a list of the ISO 639-1 two-letter language codes for languages supported by this package. For example, if the package contains translated Extensions or Interface Panels in several languages, you should list them here. For example, ["en", "ja"].
displayNames (map) - The user visible text 'title' of your package. This is a map from ISO language codes (with optional region) to Unicode quoted strings. The text used will depend on the language setting of the installer app (e.g. Smart Pendant, Smart Installer desktop). At least one key for "en" (English) is required, as it is used as a fall-back in case a translation for the language the user is using the installer with is not supplied.
displayNames: {
"en": "Calculator",
"ja": "電卓",
"de": "Taschenrechner",
"fr_FR": "Calculatrice",
"zh_CN": "计算器",
"ko_KR": "계산기",
"pt_BR": "Calculadora"
}
vendor (string; required) - The name of the vendor (creator) of the package. For example "Acme Automation Inc.".
vendorIcon (string; optional) - If supplied, a logo PNG or JPEG image of the vendor's company logo, which can be displayed to the end-user against the package. This can either be a data URI with base64 encoded PNG or JPEG data, or just a quoted name of a .png or .jpg file relative to the folder the .jsonnet template is in. (It will be read when the package is created and converted into a data URI and kept contained within the metadata rather than as a file). Recommended to be no larger than 256x256 pixels.
descriptions (map; optional) - Similar to the displayName, this can be optionally used to provide a longer description of the package content, in various languages. Like the displayNames field, this is a map of language keys to description text. An English (en) key should be provdided as a fallback.
authorName (string; optional) - The name of the author/creator of the package.
contactEmail (string; optional) - A contact email should end-users installing the package require support.
installationExpity (string date in the format "YYYY-MM-DD" UTC; optional) - If a date is supplied, the package will not be installable after the specified date. Note that it will not impact package artifacts that have already been installed prior to the date.
minRequiredInstallerVersion (string sematic version; optional) - If supplied, the minimum version of the Installer itself required to install this package. The version of the Installer within Smart Pendant typically tracks the major.minor version of Smart Pendant itself. Use this is there are specific package fields of installer features you know your package uses that are not in older versions of the installer.
requireControllerConnected (boolean true or false; required) - If true, the package will only be installable if the device running the installer is connected to a robot controller (e.g. Smart Pendant is in a connected state). If your package contains artifacts that are installed on the controller, such as robot Jobs
includesArchive (boolean true or false; optional, default false) - if the package will contain files and folder in addition to the this metadata, set this to true. When true, the packager will use the folder specified on the command-line as content to be included in the package itself (not unlike a zip file). This is used if the package contains conponents that reference data files, such as job .JBI files, extension binaries and supporting files, PRM files, etc. Some package don't contain any data files (for example, if just setting some parameters or I/O names, etc.)
controllerCompatMinVersions (list of string RC controller s/w versions; optional) - If the package should not be installed on some cotrollers with s/w below some minimum versions, you can list the versions here. If the installer is connected to a controller with a version of its controller software before that specified, the package will not be installable (won't allow itself to be installed). For example ["YAS3.10.00", "YBS2.35.00"] would require being connected to either a YRC1000 controller with software version YAS3.10 or later or a YRC1000micro with software version YBS2.35 or later.
controllerIDs (list of string serial numbers; optional, default {} empty) - If supplied, the controller hardware to which the installer is connected is required to be in the supplied list for the package to be installable. Useful to tie a package to a specific controller or controllers by their serial numbers.
requiredPermissions (list of strings; optional, default ["monitoring"]) - this is a way to specify access permission sets for the package to be installable. Typically, the named security access strings are used - one of operating, editing, managing, safety (support and administering can be used by official Yaskawa packages only). For example ["managing"] will require the end-user to gain Management access (typically by being prompted for the management pass-code, or already having obtained it). Note that the access permissions required to install the package are the union of this and any specified for specific components. Hence, if a package indicates "editing", but one component specifies "managing", then the package can only be installed once Management security access has been obtained.
suggestControllerBackup (boolean true or false; optional, default false) - if specified as true, prior to installation of the package, the end-user will be prompted to make a backup of the controller before installing the package (a suggestion only). This is a good idea if the package contains components who's installation will significantly change the controller state and it may be difficult to reverse. While packages can be uninstalled, this is not perfect, particular if multiple packages modify the same resources.
installationOverridePasscode (string of 6 digits; optional) - This is a convenience property for package creators to allow unconditional reinstallation. If the Smart Pendant is has 'Development Access' enabled (from General Settings after the developer access package has been installed) and a numeric pass-code is supplied here, the package will be installable if the correct pass-code is supplied during installation, even if the pre-requisites would normally prohibit installation. For example, once a package of a particular version, say 1.0, has been installed, it is not normally possible to install it again (since it is considered already installed), without first uninstalling it, or if a newer version of the package is avaiable. For vendors testing packages, it can be very useful to be allowed to unconditionally repeatedly reinstall the same package for testing purposes.
prohibitUninstall (boolean true or false; optional, default false) - if supplied as true, the package will not be able to be uninstalled by the end-user. This can be used if the actions of installation cannot usefully be undone, for example.
license (a map) - a map from language ISO codes (similar to displayNames) to text to be displayed as a license for agreement by the end-user prior to package installation. Use this to provide 'shrink wrap' software license text for your package. Basic HTML is allowed (excaped appropriately).
userLicenseAgreementOnce (boolean true or false; default true) - if true, the license text will only be presented to the end-user once the first time a package with this canonicalName is installed. On subsequent installations (e.g. for later versions of the same canonicalName or if the package allows repeated reinstallation) the license text will not be presented again. If false, it will be presented for every installation, even if the device has had the package installed before.
metadata (map; optional, default empty) - a map of key,value strings for extended package metadata (allows for additional data without modificatin of the metadata format itself). For package creators, one useful supported key is allow_reinstall. To allow the package to be repeatedly reinstalled (even for the same version number), use { allow_reinstall: 'true' } (note 'true' is a quoted string in this context).
prerequisites (map representing InstallConditions; optional) - This allows specifying a list of criteria that must be satisfied before the package can be installed. There are a number of criteria supported and the details are documented in the section below.
prompts (a list of maps representing InstallPrompts; optional) - This allows prompting the end-user with a set of questions prior to the instalation of the packages (for example, to decide which components to install). The prompts may be simple Yes/No questions, multple choice or selections from a list. The resulting answers can be set in a user-definable 'install varable' which can be referenced by package component conditionalInstall or prerequisites property. For example, this may be used to create a package containing artifacts suitable for multiple hardware devices from the vendor, only one of which the end-user may have. In this case, a prompt could allow the user to select which hardware they have and then only install variants of the artifacts suitable for their hardware. The format for specifying prompts is detailed in a section below.
The same 'InstallConditions' structure is used in mutiple places, including the package-level prerequisites property, a component's prerequisites property and also a component's conditionalInstall property. Each of these properties are a map ({}) with the following properties nested within it:
version (optional, number) - currently 1packagesInstalled (optional, list [ .. ], default empty) - list of Artifact Descriptors (for other packages - see below). Will be satisifed if the exact or a newer version of the referenced package is already installed.componentsInstalled (optional, list [ .. ], default empty) - list of Artifact Descriptors. Will be satisfied if the exact of a newer version of the referenced component is already installed.packagesNotInstalled (optional list [ ..]) - as for packagesInstalled except the condition is satisfied if no such package (or a newer version) is installedcomponentsNotInstalled (optional, list [ .. ]) - as for componentsInstalled except the condition is satisfied if no such component (or a newer version) is installed.languagesSupported (optional, list [..] of strings) - a list of language codes (with optional regions). The condition is satisfied if the installing device (e.g. pendant) supports all of the specified languages.controllerModel (optional, string, default empty) - condition is satisfied if the connected controller model matches this. (Empty indicates any model). One of yrc1000, yrc1000micro, ynx1000 or `` (empty)robotCount (optional, number, default -1) - satisfied if the number of robots configured in the controller matches this number. -1 signifies any number.baseCount (optional, number, default -1) - satisfied if the number of bases configured in the controller matches this number. -1 signifies any number.stationCount (optional, number, default -1) - satisfied if the number of stations configured in the controller matches this number. -1 signifies any number.robotNumAxes (optional, list [ .. ] of numbers) - for each robot confgured in the controller, satisifed if the number of axes matches the number in the corresponding index position (use -1 for any nunber of axes)baseNumAxes (optional, list [ .. ] of numbers) - for each base confgured in the controller, satisifed if the number of axes matches the number in the corresponding index position (use -1 for any nunber of axes)stationNumAxes (optional, list [ .. ] of numbers) - for each station confgured in the controller, satisifed if the number of axes matched the number in the corresponding index position (use -1 for any nunber of axes)robotModelPatterns (optional, list [ .. ] of string) - satisfied if the robot model string matches at least one of the specified strings. Strings may contain a wildcard * character to match a range of any character. e.g. *HC10*applicationType (optional, string, default empty) - satisfied if the controller's configured application type matches this. One of arcwelding, handling, spotwelding, sealing, paint, lasercutting, palletizing, general, spot_gm, motorgun or laserwelding. Use the empty string for any application type.controllerParamValues (optional, list [..] of string, default empty) - a list of controller parameters and value expressions to be matched for the condition to be satisfied. The parameters may be controller-specific. For example "S2C123=23" will be satisifed if the controller's S2C123 parameter has the value 23 at installation.jobsPresent (optional, list [ .. ] of string) - a list of job names which must be present on the controller to satisfy the condition. These should be the names shown on the pendant (not the filename with .JBI extension)expression (optional, string, default empty) - an optional boolean expression that will be evaluated and, if true, the condition will be satisfied. The condition can reference installation variables set, for example, via installation prompts (see below).
= and <> operators, AND, OR and NOT, to combine and negate conditions and ( ) for grouping"(device = 'gripper1' OR device = 'gripper2') AND (device <> 'camera')"An artifact descriptor is a way to reference another package or component. It is primarily the canonical-name and version pair, but optionally also includes a display name that can be shown to the user.
For example, if a package lists a requirement for another package to be installed already (i.e. using a prerequisites Conditional Installation packagesInstalled property), the installer can easily check the installation database to determine if the package is installed or not. However, if the user should be notified about what action to take (i.e. to install the required package), it will need a user displayable name for the required package, but won't know that since it may not have seen the package before, given it isn't installed. That is the reason a display name is also provided by the requiring package - so that it can be displayed to the user. The arifact descriptor is a map/object with the following properties:
canonicalName (required, string) - the canonical name of a package, component or other artifact (e.g. com.mycompany.mydepy.acmeextensionalpha1)version (required, a Version object/map) - a version string in Semantic Version format (semver.org. The Version is actually an object with a v property (for historic reasons) - e.g. { v: "1.0.1" }displayNames (optional, map/object { .. }) - map of language codes to strings representing the display name for the referenced artifact in UTF-8 in the indicated language. e.g. { en: "Acme Robot Extension", ja: "Acmeロボット拡張機能" }For example,
{
canonicalName: 'com.mycompany.mydept.acmeextensionalpha1',
version: { v: '1.0.0' },
displayNames: {
en: "Acme Robot Extension",
ja: "Acmeロボット拡張機能"
}
}
The package-level property prompts is a list ([]) of one or more prompts to be shown to the user upon installation. Each entry is a single prompt, in the form of a map ({}) containing the following properties:
title (map of language codes to strings; required) - the title of question (typically shown as the title of a pop-up window). This is a map from ISO language code to the title in that language. e.g. { en: "Install Extra Preset?" }text (map of language codes to strings; required) - the text of the question itself. e.g. { en: "Would you like to install an extra Preset for conveniently configuring tools for this gripper?" }options (a list of maps; required) - this is a list of the options to which the user can select an answer to this prompt. Each option has a value to be used in the package metadata (assigned to the variable), along with a corresponding display label (as a map from language keys). It is possible to have only a single option (e.g. "OK"). For example,[
{
value: "installit",
label: {en:"Yes", de:"Ja"}
},
{
value:"skipit",
label: {en:"No", de:"Nein"}
}
]
Note that the strings "installit" and "skipit" are user-defined, to be assigned to the variable for comparsion in conditional installation expressions.
variable (string; required) - a user defined variable name, which can be referenced in Conditional Installation expression strings to query the value the user responded with. This should be a valid identifier (a-z A-Z 0-9, not starting with a digit - no spaces)
allowMultiple (boolean true or false; optional, false) - if true, rather than the user being allowed to select one of the options provided, they will be able to select multiple of them. Useful if the options don't represent a mutally exclusive list (e.g. a list of hardware devices for which they may have more than one).
defaultOptions (list of strings; optional) - provide a default option (or potentially multiple if allowMultiple is true) to be used in contexts where the user cannot be prompted. For example, non-interactive installation via Smart Installer. May be empty. The values of provided in the list must match the value strings for the options.
For example, if the variable is named "installthething" and the user responded to the prompt example above by clicking "Yes" (when using English), the variable will be set to the value "installit". The conditional install expression (installthething="installit") will be true in this case. It is good practice to choose sensible variable and value strings - this example is deliberately whimsical to avoid confusion between property names and user-supplied strings.
The package-level components field is a list ([]) of any number of components to be installed when the package is installed. All the component types share some common properties, which provide versioning, pre-requisites for installation and various other information.
The common fields are nested within the component's { and } map delimiters (see the example above):
canonicalName (string; required) - a unique machine-readable identifier to refer to the component. Like packages, components are uniquely identified by this, combined with the componentVersion.
componentVersion - (map; v key required) - The version of this component.
Assigning a version number to your component allows the installer to understand if the component is already installed, or if an older version is installed and can be updated to a newer one, etc. The format follows the Semantic Versioning standard (see semver.org) or 'MAJOR'.'MINOR'.'PATCH'. For example, "1.0.0". Note that the elements increase numerically independently, so "1.9.0" is a lower verson than "1.10.0" since 9 is smaller than 10. The value is a map (JSON object) with a "v" key (for historical reasons) - for example { v: "1.0.0" }. Typically, if a package is being installed, but there is already a component installed with the same or lower version, the component will not be (re)installed. This allows sharing components across packages, such thay they'll only every be upgraded upon installation, never downgraded.
type (string; required) - This identifies the specific kind of component. Must be one of (quoted) jobs, tools, options, ionames, variables, fieldbus, panels, alarms, extension, motoplus, files or network. This determines which component-type-specific properties are relevant from the sections detailing each component type below.
description (string; optional) - This is an internal description. It will appear in log files but it not displayed to the end-user (and doesn't have language translations)
modifiesController (boolean true or false) - May be predefined according to the type of component. Set to true to indicate that installation of the component will modify the controller (e.g. jobs, I/O Names etc).
skipWithoutController (boolean; optional, default false) - If false, if no controller it connected to the installer device, the package will not be installable. If true, the package can be installed without a controller connection, but this component will be skipped (not installed).
metadata (map; optional, default empty) - a map of key,value strings for extended package metadata (allows for additional data without modificatin of the metadata format itself).
conflictOption (string; optional, default "default") - When there is a conflict between this component during installation, this specifies how it should be handled by the installer. One of:
"query" - Ask the user what do to (i.e. skip installation, overwrite the existing artifact or abort the package installation)"default" - Take the default action (as specified in the conflictDefaultAction property of this component)."fail" - Abort the component (and hence package) installation with a failure notice.conflictOption is set to "query", the user will be prompted to choose between skipping this job, overwriting the existing job with the job in the component or aborting the installation."query" option will be treated like "default".conflictDefaultAction (string; optional, default "overwrite") - One of "skip" to skip installing the conflicting artifact, or "overwrite" to replace any existing artifact by installing the one supplied by this component.
requiredPermissions (list of strings; optional, default ["monitoring"]) - this is a way to specify access permission sets for the component to be installable. Typically, the named security access strings are used - one of operating, editing, managing, safety (support and administering can be used by official Yaskawa packages only). For example ["managing"] will require the end-user to gain Management access (typically by being prompted for the management pass-code, or already having obtained it). Note that the access permissions for all components are aggregated along with those for the package as a whole, to determine the access requirements for installing the package.
prerequisites (map representing InstallConditions; optional) - This allows specifying a list of criteria that must be satisfied before the component, and by implication the whole package, can be installed. There are a number of criteria supported and the details are documented in the Conditional Installation section above. If the prerequisites are not satisfied the package itself will not be installable.
conditionalInstall - (map representing InstallConditions; optional) - A list of criteria that, when satisfied (if installIfConditionsSatisfied is true), allow the component to be installed. Otherwise, if not satisifed, the component will be skipped (but it will not itself prevent the package as a whole from being installable). See the Conditional Installation section above for details.
This is useful for including variants of a component in a package that are applicable in different contexts. For example, if a different MotoPlus app is required for YRC1000 vs YRC1000micro, a component for each controller model can be included in the same package such that only the appropriate one will be installed dependent on which controller model the installer is connected to.
installIfConditionsSatisfied (boolean true or false; default true). Controls the sense of the conditionalInstall conditions for the component. In the default case, if the conditions are satisfied, the component will be installed. Conversely, if this is explicitly set to false, then if the conditionalInstall conditions are satisfied, the component will be skipped (not installed) instead.
restartController (boolean true or false; default false) - Require that the robot controller is restarted (CPU board power-cycled) after this component has been installed, before continuing with successive components in the package (if any). Note that, for T150 Smart Pendant, restarting the controller also causes the T150 to restart the pendant. In this case, the Smart Pendant will go through its regular startup procedure and then the package installation will be resumed with the next component.
safetyFlashReset (boolean true or false; default false) - Set this to true to force a Safety Flash Reset operation on the controller after this component has been installed.
The type-specific properties for each component are nested in a map property with the same name as the type.
For example:
{
// package-wide properties
// ...
components: [
{ // first component, common properties:
canonicalName: "com.yaskawa.example.somejobs",
type: "jobs",
modifiesController: true,
// ...
jobs: { // Jobs component specific properties
languageCode: "en"
// ...
}
}, // end component
{
// ... another component ...
}
]
}
The Jobs component (type jobs) allows the inclusion of INFORM .JBI files in the package. The jobs will be copied to the controller during package installation.
jobs (list of maps, required) - a list ([]) of jobs to be installed by this component. Each job is a map with properties as listed below. Can be an empty list.version (number, optional) - the version of the Jobs Component format. Unless using specific features added in later format updates, it is best to leave this unspecified.languageCode (string, optional) - the ISO two-letter language code of the job (to identify the encoding if needed). e.g. "en" or "ja"defaultJob (string; optional) - If a job name is specified (not a filename), the installer will attempt to set the controller's default (aka master) job to the specified job.Each Job is a map with properties:
jobName (string, required) - The name of the jobs as it will appear on the pendant Jobs List..JBI file header (text format). This name must match the name within the .JBI file or the job will fail to upload to the controller.jobLanguage (string, required) - currently must be "INFORM"jobFileName (string, required) - The filename for the job source in the archived content (e.g. the .JBI file)..JBI text encoding that predates Unicode. The encoding used depends on the language settings configured on the controller. The file content should be appropriate encoded (it is not modified by the packager or installer). The best way to achieve this is to start with a job exported from the controller and/or to limit text to the ASCII Latin characters. For example, jobs for a controller configured for Japanese use Shift-JIS encoded .JBI files.jobFolderPath (string, required) - The path prefix for job source file. It is good practice, if including multiple job files and other artifacts, to place your job files in a subfolder of the archive (say, "jobs"). If you have different job file sets for different contexts, you can further organize them into sub-sub-folders.jobType - (string, required) - Must be "robot".jobControllerGroup (string, required) - only "R1" currently supported.An example:
// ... common component properties ...
jobs: {
// Jobs Component type-specific properties:
defaultJob: "OR_WL_SETPROGID",
jobs: [
{
"jobControllerGroup": "R1",
"jobFileName": "OR_WL_SECSTOP.JBI",
"jobFolderPath": "jobs/WL",
"jobLanguage": "INFORM",
"jobName": "OR_WL_SECSTOP",
"jobType": "robot"
},
{
"jobControllerGroup": "R1",
"jobFileName": "OR_WL_SETPROGID.JBI",
"jobFolderPath": "jobs/WL",
"jobLanguage": "INFORM",
"jobName": "OR_WL_SETPROGID",
"jobType": "robot"
}
]
}
The Tools component (type tools) allows inclusion of Tools presets files (.yps files), which will be installed on the pendant. It will not make any changes to the controller during installation, but the presets will be available for selection by the customer when editing tool properties.
(Official Yaskawa packages may also directly setup tool properties for new controller configuration; not documented here)
presetFiles (list of maps; optional, default empty) - a list of 'PresetFile' maps, one per preset, as detailed below. Note that any given preset file can contain multiple tools presets.A 'PresetFile' is a map with the following properties:
filename (string, required) - The filename, relative to the package archive root, of the presets file (.yps)presetIds (list of strings; optional, default empty) - a list of preset ids contained within the specified presets file (to support uninstallation)apply (boolean true or false; optional, default false) - omit or false except for official Yaskawa packages. If true, the preset is actually applied to tool settings on the controller.params (map; optional, default empty) - Preset-specific additional parameters. Only used if apply is true. (e.g. toolnum: "1")The Options component (type options) allows setting robot controller parameters during installation. The parameter names, allowable values and their meaning is documented throughout the robot and controller manuals where appropriate.
controllerParamValues (map of parameter names to values, required) - the map keys are strings of conroller parameter names, such as "S2C219" to values, such as "10". Only the parameters with prefixes "S1CG", "S2C", "S3C", "S4C", "RS", "AP" are allowed.requireControllerRestartOnChange (boolean true or false; optional, default false) - if true a controller restart (hence, potentially a pendant spp restart) will be triggered after the parameters have been setoptionSettings - unused.configEdits - Yaskawa official internalExample of setting two S2C parameters, overwriting their existing values:
components: [
{
canonicalName: "com.yaskawa.yii.test.params1.params",
componentVersion: { "v": "1.0.0" },
type: "options",
conflictDefaultAction: "overwrite",
conflictOption: "default",
modifiesController: true,
options: {
controllerParamValues: {
"S2C219": "1", // External Start Permitted -> OFF
"S2C293": "1" // First Playback Cycle in Remote -> One Cycle
}
},
skipWithoutController: false
}
]
This component (type ionames) provides a way to selectively set I/O names or replace (overwrite) all I/O names with an IONAME.DAT file. It supports setting individual I/O (bit) names or setting I/O group names (which auto-numbers the individual I/O bits with a suffix). By using the component-level conflictOption documented above, you can specify if conflicts with existing I/O names on the controller should cause failure, left as-is or the user prompted for what action to take.
ionameDatFile (string, optional) - The filename, relative to the package archive root, of an IONAME.DAT file to be written to the controller (overwriting all existing I/O names). This is applied first before any of the ioNames properties (if they are present).
ioNames (list of maps, required; default empty) - a list of I/O name entries to be applied. Each is a map with the properties below.
Each ioNames map element has the following properties:
type (string, required) - One of "inputs","outputs", "ingroups" or "outgroups". Determines if the names & first index below are to be applied to inputs, outputs and either individual I/O bits or groups (bytes or multi-bytes groups).size (number, required) - one of 1 (individual I/O bits are named), 8 (groups/bytes), 16 or 32 for multi-bytes groups.first (number, required) - the index of the first I/O or group. The application of names will begin at this index and subsequent indices according to the length of the names list.names (list of strings, required) - a list of strings of I/O or group names.Note that since ioNames is a list of potentially multiple lists of names to be set at various first offsets spans (the length of names) this component can set an arbitrary number of disjoint spans of I/O or group names.
The Variables component (type variables) can be used to set names and/or values of variables (such as B, I, D, R, S, and P variables).
version (number, required) - the version of the Variables Component format. Currently version 1.controllerType (string; required) - Controller type the variables apply to. May include wildcards. e.g. "yrc1000", "yrc1000micro", "*" (any). Currently unused.variables (list of list of 3 strings, required) - a list of variable entries to be applied. Each element is itself a list of 3 strings (positionally, not map of keys to values):
"B001", "I002", "P006" etc.Position variables are represented as short JSON strings. For example:
"{f:r,c:[100.230000,-75.170000,257.010000,180.030000,-87.130000,14.230000],cl:[0,0,0,0,0,0],t:2}"
The JSON map keys are:
f - frame, one of j (joint), w (world), b (base), r (robot), uN (user frame N, where N is a number), tN TCP for Tool Nj - joints, a list of DOF joint values (in degrees)c - Cartesian, a lisr of 6 values, the first 3 are XYZ Cartesian coordinates in mm. The last 3 are Euler RPY values of the orientation, in degrees.t - tool, a number (the tool associated with the position)cl - closure, a list of joint closure values (0 or 1). If empty list, assumes all 0s.The FieldBus component (type fieldbus) currently only supports Ethernet/IP settings. They can either be specified directly in the component, and/or a Presets file specified for installation.
type (required) - Currently only EtherNetIP supported.hasAdapter (optional, default false) - are Ethernet/IP adapter settings specified?adapter (required if hasAdapter true) - a JSON map object ({ .. }) with the following adapter properties:
active (optional, default true) - is the adapter active? (true or false)inputGroup (required, int) - I/O group(byte) number for inputs (whole number)outputGroup (requird, int) - I/O group(byte) number for outputs (whole number)inputInstance (required, int) - input instanceinputSize (required, int) - input instance size (often 1)outputInstance (required, int) - output instanceoutputSize (required, int) - output instance size (often 1)configInstance (required, int) - configuration instanceconfigSize (required, int) - configuration instance size (sometimes 0)scanners (optional, default empty; list [ .. ]) - a Scan List, where each element is a Scan List Entry with the properties below)
inputGroup (required, int) - I/O group(byte) number for inputs (whole number)outputGroup (requird, int) - I/O group(byte) number for outputs (whole number)ipAddress (required, string) - IP address (IPv4 x.x.x.x format quoted string)inputInstance (required, int) - input instanceinputSize (required, int) - input instance size (often 1)outputInstance (required, int) - output instanceoutputSize (required, int) - output instance size (often 1)configInstance (required, int) - configuration instanceconfigSize (required, int) - configuration instance size (sometimes 0)connectionRPIot (optional, default 20) - Connection RPI Originator to Target in millisecondsconnectionRPIto (optional, default 20) - Connection RPI Target to Originator in millisecondsinstanceNoSize (optional, default 2) - instance number bytes, 1 or 2connectionType (optional, default ExclusiveOwner) - connection type; one of ExclusiveOwner, InputOnly or UserconnectionTimeout (optional, default Timeout4Tries) - number of connection retries before timeout error; one of Timeout4Tries, Timeout8Tries, Timeout16Tries, Timeout32Tries, Timeout64Tries, Timeout128Tries, imeout256Tries or Timeout512Triesname (required; string) - a name for this scan list entrycomment (optional, default none) - an optional commentpresetFiles (optional, default empty; list [ .. ] of Preset File entries, each a JSON object map with the following propertes)
filename (required, string) - filename of the Preset file (.yps) within the package archive, relative to its root. Note that a single .yps file may contain multiple Presets.apply (optional, default false) - if true, apply the presets within the fileparams (optional, default empty; list [ .. ] of object maps of key: value pairs) - additional preset-specific parametersapply is true, it may be necessary to supply additional missing parameters (using property names used by Presets files), such as ingroup, outgroup, ippresetIds (optional, default empty; list [ .. ] of string ids) - if known, the list of preset ids present within the Presets file (to aid uninstallation)The Panels component (type panels) provides a way to have a single panel installed. In order to support multiple languages, the component allows including multiple panels for different languages. The panel installed will depend the user's currently selected language. Panels will only be installed if they are not already installed, based on panel id and version (unless package metadata properties allow_reinstall or allow_downgrade are true).
panels (required, object map) - { code : panelFile, ... } of language code -> a PanelFile, who's properties are detailed below. The language codes are ISO 2-letter codes (e.g. "en", "ja", "es", "de") with optional region specifier (e.g. "zh-CN").
panelid (optional, string) - should match the panelid of the contained panel .ypn fileversion (optional, string) - an object with a v property (e.g. { v: "1.0.0" }) which should match the version of the contained panel .ypn filename (required, string) - the name of the panel, in the appropriate language (UTF-8 encoded string)filename (required, string) - path and filename of the .ypn panel file, relative to the package archive rootThe Alarms component (type alarms) enables installing customized alarm text.
version (optional, number) - component format version (currently 1)language (optional, string, default empty) - ISO 2-letter language code (e.g. "en", "ja", "de", "es", "zh_CH", ...)alarms (required, list [ .. ]) - of alarm objects/maps, with the following properties
alarmFileName (required, string) - filename of alarm file (e.g. .csv)alarmFolderPath (required, string) - path of file relative to the package archive rootThe Extension component (type extension) specified the information for installation of an Extension (plugin). For example, for Smart Pendant interface extensions. These are custom executables and associated files that are run in a standardized envronment on the pendant hardware. See the Smart Pendant Extension SDK documentation.
version (required, number) - component format version (currently 2)requireAPIVersion (required, Version) - object with v property (e.g. { v: "3.0" }) - minimum required Extension API version requiredsupportedLanguages (required, list [ .. ] of strings) - the languages codes supported by this extension (ISO 2-letter with optional region, e.g. "en", "ja", "zh-CN")displayNames (required, object/map { .. }) - map of language codes keys to extension display name (UTF-8) in the key code language - the name displayed to the user will depend on their current language settingrequiredPlatform (required, string) - e.g. armhf:linux, androidrequiredRuntime (required, string) - one of openjdk11,netcore22,net60, ...extensionDependencies (optional, object/map { .. }, default empty) - map of canonical-name -> Version pairs of requirements of this extension. Note the Version is itself a map such as { v: '1.0.0' }configuration (optional, object/map { .. }, default empty) - map of configuration key (string) : value (string) pairs, which can be obtained by the extension codeiconName (optional, string) - name of a file containing a square icon representing the extension (shown to the user). If absent, the package vendor logo icon may be used instead.extFolder (required, string, default empty) - the folder relative to the archive root containing this extension (empty for the root itself)keepFilesOnUpdate (optional, default true) - when an updated version of the extension is installed and an existing (older) version is already installed, if true the installer will unzip (overwrite) the package files in the existing extension's folder. If false the installed older extension content will be deleted before installation of this newer extension.requireNetworking (optional, default false) - if true the extension will be allowed network access (e.g. to the local network or the Interface if accessible). If false it may be blocked by a firewallrestrictedInterface (optional, default false) - if true, when the extension is installed, some interfaces (e.g. the pendant) may have restructed functionalityprotectLogs (optional, default false) - if true, the extension's log files will not be readily accessible by users. If false they will be available to all. Note that the logs can be accessed by a knowledagble user on some platforms (e.g. Android).executableFile (required, string) - filename of the executable binary or script to be launched to run this extension. As a convenience, if this is a Java .jar file it will be launched with the java JVM with some predetermined parameters.executableFileOptions (optional, string, default empty) - additional command-line options string to be passed to the executable for normal launchpostInstallExecutableFile (optional, string, default empty) - filename of an executable to be launched after extension initial installation (can be the same as the executableFile, in which case you should pass distinguishing options)postInstallExecutableFileOptions (optional, string, default empty) - additional command-line options string to be passed to the post installation executable (if any)preUpdateExecutableFile (optional, string, default empty) - filename of an executable to be launched prior to the installation of an updated version of the extension (only if keepFilesOnUpdate is true)preUpdateExecutableFileOptions (optional, string, default empty) - additional command-line options string to be passed to the pre-update executable (if any)preUninstallExecutableFile (optional, string, default empty) - filename of an executable to be launched just prior to the uninstallation of this extension (if supplied)preUninstallExecutableFileOptions - additional command-line options string to be passed to the pre-installation executable (if any)The MotoPlus component (type motoplus) is for installing MotoPlus applications on the controller. These are controller-specific binary files (typically compiled from C/C++) that execute directly in the real-time OS environment of the controller. As such, it should always be ensured that the apps are 'well behaved' - for example, not 'busy waiting', which may interfere with the operation of the controller or connected devices (such as the pendant).
version (required, number) - currently must be 2motoplusName (required, string) - the name of the MotoPlus app as represented in the controllermotoplusFileName (required, string) - the filename (e.g. ending in .out) of app binarymotoplusFolderPath (required,string) - the path, relative to the package archive rootcontrollerType (required) - one of YRC1000, YRC1000micro or YNX1000controllerMinSoftwareVer (required, string) - minimum version of RC software required (e.g. "YAS5.40"). Only compares based on the MAJOR.MINOR numbers.motoplusRemoveOldApp (required, list [ .. ], can be empty list) - list of strings of old Motoplus app names to remove before installationmotoplusConflictApp (required, list [] .. ], can be empty list) - list of strings od MotoPlus app names that will conflict with this app (and hence, this app cannot be installed if they are installed)skipControllerTypeMismatch (optional, default false) - one of true (skip installation if the controllerType doesn't match) or falseThe Files component (type files) allows the installation or editing of files on the controller or the pendant. The files that can be installed is limited to those supported for File Transfer via the pendant interface (- except for Yaskawa official packages, which may install any files). In addition, files can also be renamed or deleted (optionally, upon package uninstallation only).
For Yaskawa packages only: It is also possible to provide package files, like .zip files and have them unzipped (on the pendant); and to run shell commands.
Files Sets list files to be installed (copied), renamed or deleted.
fileSets (optional, default empty; a list [ .. ] of File Set object maps) - one entry per file, with the following object properties:
requiredPlatform (optional, default empty(any); string) - platform requirement for this entrytype (required, string) - one of files, archives, packagessource (optional, default empty; string) - source folder relative to package archivedestination (optional, default empty; string) - host system dest folder if files or archive. Prefix with yrc: to target controller (files only).autoCreateDestination - if destination is dir, create as necessarynames (required, list [ .. ] of strings) - filenames of files relative to source (& dest). If name1->name2 format, assume renamereplace (optional, default true) - unconditional overwrite if true, skip if exists otherwisedeleteDest (optional, default false) - if true, delete files instead of copying (relative to destination; source ignored), type files onlydeleteOnUninstall (optional, default false) - if true, the destination files copies on installation will be deleted upon uninstallationlog (optional, default none; string) - if not empty, text will be logged to the install.log upon installatoin of this component entryFile Edits allow search & replace in files or appending content to the end.
fileEdits
requiredPlatform (optional, default empty(any); string) - platform requirement for this entryfilename (required; string) - absolute path & filename of file to edittype (optional, default sr) - one of sr (search & replace) or a (append)regexSearch (optional, default empty; string) - The Regular Expression for searching the filereplace (optional, default empty; string) - text to replace each search matched (type sr)text (optional, default empty; string) - text to append to the file (type a)log (optional, default none; string) - if not empty, text will be logged to the install.log upon installatoin of this component entryonUninstall (optional; default false) - if true, make this edit during uninstall, not installCommands allow execution of shell commands on the pendant (official Yaskawa packages only).
commands
requiredPlatform (required, string) - skip unless the installer platform matches this. Can be empty or * to match any, or a specific platform, such as armhf:linux (T150), androidenv (optional, string, default sh) - the execution environment for the commandcondition (optional, string, default empty) - a condiution which must evaluate to 'true' for the command to be executedcommand (required, string) - the command-line to be executedlog (optional, string, default empty) - an optional log message to be logged when the command is executed during installationonUninstall (optional, default false) - if true this command will be executed when the component is uninstalled instead of when it is installedinternalPackageOnly (optional, default true) - if true, files are only installed if the package is an official Yaskawa packageThe Network component (type network) is for network settings, such as IP addresses, gateway IP, enabling DHCP and similar.
version (required, number) - version of the component format, currently must be 1interfaces (required, object/map { .. }) - map of interface name to settings object (properties below). The interface name should be one of LAN1, LAN2 or LAN3.
name (required, string) - name of the interface (same as map key) - one of LAN1, LAN2 or LAN3ipAddress (optional, string) - IP address for the interface (IPv4 currently). Required if source is manual.subnetMask (optional, string) - The subnet mask (e.g. 255.255.255.0 for class C). Required if source is manual.source (optional, string) - one of manual (IP address manually set by specifying above) or an interface name for DHCP source via that interfaceenabled (optional, default true) - one of true or false to enable or disable this interfacesettings (required, object/map) - map of settings properties, below
hostname (optional, string) - the host name of the controller (without domain)domain (optional, string) - the domain of the controllerhostSource (optional, default empty) - must be manual or the interface name (e.g. LAN2) used for DHCP aquisition of the hostname and domaingatewayIpAddress (optional, default empty) - the IP address of the network gateway (typically, but not always, the subnet prefix with .1 as the last number)gatewayEnabled (optional, default true)gatewaySource (optional, default empty) - must be manual of the interface name used for DHCP aquisition