Setting up the Development Workspace

Prerequisites

Before you begin, ensure that you have a running instance of the Zero4 System Application. This tutorial assumes that:

  • The Consumer User Interface will work with the Zero4 System Application you created earlier.
  • The UI development environment is optimized for live data access and debugging via a local browser.
  • The Zero4 System Application has been built into an image and deployed from kOS Studio to a running simulator or Zero4 controller.

For this tutorial, it is assumed that the Zero4 System Application is available at:

http://localhost:8081

Getting Started

The kOS UI SDK provides an integrated development platform designed to accelerate kOS UI application creation using a mix of command line tooling, libraries, and extensions.

Installing the KOS CLI

The kOS UI SDK includes a CLI tool, kosui, which helps scaffold a workspace that follows best practices for kOS UI development. Install it globally via NPM:

npm install -g @kosdev-code/kos-ui-cli

Creating a Workspace

Generate a fully integrated development workspace using the following commands:

kosui workspace training-zero4 
cd training-zero4 
npm install

Project Structure

The generated project is organized as an NX monorepo and is divided into logical packages tailored for kOS UI applications:

apps

Contains the UI applications that will eventually be deployed.

  • Example: training-zero4-ui – This is the consumer UI for the tutorial, preconfigured to work out-of-the-box.

libs

Contains libraries and support code including models, UI components, and other services tied to kOS.

  • Example: model-components – Reusable React components and hooks that interact directly with kOS models or services.
  • Example: training-zero4-models – Contains common kOS models, types, services, and extensions shared across applications.

This layered approach (apps → components → models) promotes scalability, reusability, and a clear separation of concerns.

By using this layered approach where dependencies flow downwards from apps → components → models, projects can better scale to future requirements and allow for better re-use across applications.

Tooling

VS Code Plugin

An integrated VS Code plugin is available for quick access to common functions and build tools. This plugin streamlines the development workflow by exposing these features directly within your editor.

VS Code Plugin

Dev Server

The workspace includes a development server for real-time feedback and live updates during active development. You can start the dev server using either the VS Code plugin or via the command line:

npx nx run training-zero4-ui:serve:development

Once running, navigate to:

http://localhost:4200/?host=http://localhost:8081#

This URL includes the query parameter host=http://localhost:8081, which instructs the UI SDK to connect to your running kOS service host. This is especially useful when developing against a remote backend (e.g., a Raspberry Pi) instead of using mocks or dummy data.

When this screen is presented it validates that the kOS UI SDK has been initialized and a connection has been established with the kOS Service Host meaning you can now ready to start developing your first kOS UI Application.

Kab Packaging

The environment is preconfigured to bundle applications into Kab files, which can be published to Studio or used for local testing.

Creating a Kab

You can generate a Kab file using the VS Code plugin or via the command line:

npx nx run training-zero4-ui:kab

This command creates a test Kab that Studio can automatically consume, enabling seamless integration between development and deployment.

Environment Variables for Kab Builds

When building from source, you must set up environment variables so that the tooling knows where to find Java and a local Studio installation. The kosui CLI can auto-detect and populate these variables. Run:

kosui env

This command discovers and stores the necessary environment variables in a file named .env.local at the root of your workspace:

#  Path to the Java binary
JAVA_CMD='/usr/bin/java'
#  Path to the kos installation
KOS_INSTALL_PATH='/Users/dev/Applications/kosStudio.app'

The kosui env command runs automatically when setting up a new workspace (typically immediately after cloning the repo).

With your development workspace set up and connected to the live Zero4 System Application, you are now ready to start building your first kOS UI application!