kuco v0.13.1

Welcome

kuco is a tool for developing custom views for the KUKA SmartProduction (KSP) IoT platform.

How it works

The developer's goal is simple: build a new custom view in an environment that is as similar as possible to the environment where the view will eventually be deployed. We want all out-of-the-box features and environment-specific configurations and datasets to be available during development of a custom view.

To achieve this, kuco starts a local webserver and delegates all backend calls to an existing instance of KSP (e.g. production.onkuka.com) while simultaneously intelligently splicing in any custom views being developed locally.

For example, all requests for standard Javascripts, images, styles and data will be forwarded to the proxied instance of KSP, while any calls determining the available custom views for a tenant will be intercepted by kuco, thus allowing developers to use their local, under-development views in the context of a real, deployed instance of KSP.

Getting Started

Set up our working directory

The first step is to create a working directory for our custom view project:

$ mkdir my-first-kuco-project
$ cd my-first-kuco-project

Then, we need to install kuco locally:

$ npm install -g kuco

Create a new asset view

Create a simple asset view:

$ kuco view:addAssetView hello-world

A quick directory listing shows us that kuco has initialised our working directory:

$ ls -la

drwxr-xr-x   4 someuser  staff   136 Aug 16 14:30 .
drwxr-xr-x+ 93 someuser  staff  3162 Aug 16 14:30 ..
-rw-r--r--   1 someuser  staff   408 Aug 16 14:30 config.json
drwxr-xr-x   3 someuser  staff   102 Aug 16 14:30 kuco

The file config.json contains all metadata on the views in this module. While this file can be edited manually, this is usually a bad idea and should be left to kuco.

The directory kuco contains the resources that make up our custom view(s). Each view resides in the directory kuco/views/VIEWNAME, in our case for example kuco/views/hello-world.

Configure the asset view

Like in the production environment, KSP needs to be told which custom view is to be displayed under which circumstances.

Asset views can be associated with an asset type and/or an asset's serial number:

$ kuco view:associate hello-world assetType type42

This will result in all assets with the asset type type42 being shown in our new custom view rather than the KSP system default view.

Start local webserver

Now that we have a custom view and have configured when it is to be displayed in place of the KSP default view, we can start up the local webserver:

$ kuco serve

During start-up, you will be prompted for various things:

• GTC needs to be accepted (only once)
• choose the domain you want to connect to (usually this domain includes your tenant as well as the environment - e.g. for a tenant named 'stark' where we want to connect to the staging environment: 'https://stark-staging.onkuka.com')
• choose whether you want to edit the existing webapplication (internal) for example by creating new asset views / services OR you want to create a whole new webapplication (external). When in doubt, use "internal".
• if you chose the option 'internal' you can start developing right now. If your selection was 'external' you need to log in (at the moment only via 'KUKA Connect' is available) and type in a url you want to grant access to the API. When your application is running under 'localhost:1234', just type so. Now your application has access to the API.

And just like that, you can check out your custom view by navigating to a suitable asset:

http://localhost:1138

Troubleshooting

One common problem when deploying a set of views is that the files present on the developer's machine and the files explicitly listed in the config.json file diverge: for example, a CSS file might reference an image file that wasn't included in the file list.

The following command can be used to see a list of potential problems: files that are found in the view's local directory but are not referenced in the config.json file, and vice versa.

$ kuco view:listFiles myHelloWorldView

The view name can be omitted; in this case, the command will be applied to all views found in the config.json file.

Further information

For more information on the available features in kuco, use the command:

$ kuco -h

Migrations

Not all upgrades of kuco are 100% backwards compatible, and will require manual migration effort.

Upgrading to kuco 0.6.x

Release 0.6.0 of kuco introduced two breaking changes to existing kuco modules:

• Each view within the module's directory must reside in MODULE_DIR/kuco/assetViews/MODULE_NAME, instead of the previous MODULE_DIR/custom/assetViews/MODULE_NAME
• The module descriptor file config.json must reside directly in MODULE_DIR, i.e. it now resides alongside the kuco directory, instead of inside it.

All affected modules will have to be manually migrated:

• Rename the directory "custom" to "kuco", and replace all references to "custom" with "kuco" in the module descriptor file config.js and any AngularJS controllers that load template files.
• Move config.json from "kuco" to the module's root directory.