Kvaser CanKing GUI Extensions SDK

Introduction

The purpose with this package is to help developers to create user interface extensions for the Kvaser CanKing bus analysis tool.

Kvaser CanKing is a free of charge, general-purpose CAN and LIN bus analysis software that is compatible with all Kvaser CAN and LIN interfaces and the Kvaser virtual CAN bus. It's available on Windows (x64) and Linux (x64 and ARM).

There are a lot of functionality already included in the base version of CanKing, but it is also possible to extend the functionality and the user interface by creating extensions.

An extension is developed as a stand-alone React web application. The web application will be hosted by an express web server inside CanKing and it will be mounted into the CanKing user interface using a webview element.

When an extension is mounted into CanKing, then a preload script will run to inject inter-process communication (IPC) functions. These functions will make it possible for the extension to communicate with CanKing to get information and to interact with the CAN/LIN bus.

The IPC functions are accessible by importing different modules from the @kvaser/canking-api package.

To get or subscribe on CanKing data there are different React hooks to be used. All these can be found in the hooks module.

import { useUserSetting, useMeasurementSetup } from '@kvaser/canking-api/hooks';

...

const userSettings = useUserSettings();
const measurementSetup = useMeasurementSetup();

To interact with CanKing there are different functions that can be imported from the ipc module.

import { sendCanMessage } from '@kvaser/canking-api/ipc';

...

sendCanMessage(channelId, frameId, data, flags);

The @kvaser/canking-api package also includes some React components that you can use, e.g. there is a component for selecting channel.

import { CanChannelSelectControl } from '@kvaser/canking-api/controls';

...

function WorkspaceView() {
  const [channelId, setChannelId] = useState('');
  return (
    <CanChannelSelectControl
      channelIdentifier={channelId}
      onChannelIdentifierChange={setChannelId}
      hideSectionControl
    />
  );
}

Prerequisites

Before creating a new CanKing Extension the following softwares need to be installed.

Node.js: https://nodejs.org/
Kvaser CanKing: https://kvaser.com/canking/
Kvaser Drivers: https://resources.kvaser.com/7330130980013/latest/kvaser_drivers_setup.exe

You will also need an IDE (Integrated Development Environment) to edit and debug your code. We recommend that you're using Visual Studio Code.

With Visual Studio Code you might also want to install these extensions to help you with code formatting and code analysing:

Generate a new CanKing Extension project

The simplest way to create a new CanKing Extension project is to use the script that is included in the @kvaser/create-canking-extension package. The script is used like this:

npm create @kvaser/canking-extension@latest

Then follow the prompts.

You can also specify a project name via a command line argument.

npm create @kvaser/canking-extension@latest my-ck-extension

This command will create a new project in a new folder with the same name as the specified project name (my-ck-extension). You can use . for the project name to scaffold your project in the current directory.

The command above will create a folder structure like this:

my-ck-extension
│   .gitignore
│   .prettierrc
│   eslint.config.mjs
│   index.html
│   package.json
│   tsconfig.app.json
│   tsconfig.json
│   tsconfig.node.json
│   vite.config.ts
│
├───.vscode
│       launch.json
│
└───src
    │   App.tsx
    │   main.tsx
    │   vite-env.d.ts
    │
    ├───assets
    │       icon.png
    │
    └───WorkspaceView
            index.tsx

The project follows a similar file structure as the one that is created for a Vite project created using the react-ts template. There are some extra information added to the package.json file that are needed for CanKing and the src files are modified to be used inside CanKing.

The my-ck-extension/src/WorkspaceView/index.tsx file is the file that includes the React component that will be mounted into CanKing, so this is the file you should implement to create your extension.

Develop a CanKing Extension

To match the CanKing look and feel, it's recommended to use Material UI components when applicable, https://mui.com/material-ui/all-components/.

The WorkspaceView React component (src/WorkspaceVew/index.tsx) will be displayed when the extension is loaded into CanKing, so this is the component that should be implemented to implement the extension.

To run the extension from command line enter:

npm run start

To run the extension using Visual Studio Code debugger:

Select 'Run and Debug' or press Ctrl+Shift+D
Select the configuration named 'Debug'
Click on 'Start Debugging' or press F5

To run a production build of the extension you can enter this command:

npm run startpreview

If you need more information and help about how to interact with CanKing then you can run this command:

npx @kvaser/canking-api --help

This will open up a help file in your web browser.

Package and Install a CanKing Extension

To package your extension for distribution you should run this command from the command line:

npm pack

This command will create a tarball file in the root folder of your project called:

<project-name>-<version>.tgz

This tarball can then be installed in CanKing using the head menu 'More'->'Extensions'->'Install'.