Getting Started with Node.js

The Node.js SDK is an npm (Node Package Manager) module named HMKit which enables your web application to use car APIs. This tutorial will show you how to work with it and help get you started.

Table of Contents

Introduction and Setup

Requirements

HMKit Node.js SDK requires node v10.0.0 or higher.

Integration

There are sample applications which showcase different features. These can be downloaded on the Samples page.

Add the module

If you already have a Node.js project, download the HMKit package with node package manager by running npm install hmkit.

Create an App

In the Develop tab you will find your apps. In the app details page you are going to set the permissions it requires, manage devices and link virtual vehicles from your garage to test. Let's see how to create a new app.

  1. Go to the Develop tab, click the big plus (+) button and select Cloud App. Enter a name and continue.
  2. In the left section, select the permissions that your app needs under the "Permissions" tab. For the purporses of this tutorial, you will need to toggle the "Show all permissions" button, expand the "Door locks" capability, and select "Positions" and "Lock unlock doors" before pressing "save".
    Note: Each permission must now manually be added to each new app.
  3. You can edit your app name and image from the menu icon next to the app name.

Create a Vehicle

In the carmaker workspaces you will be able to create vehicles or other items to link with your app and to test with the emulators.

  1. Go to a carmaker workspace, click the big plus (+) button and select one vehicle to start. Enter a name and continue.
  2. You will find the vehicle capabilities listed to the left.
  3. Click on the "Launch emulator" button to see the new vehicle. Next, initialise the SDL and link the vehicle with an app.

Initialise the SDK

For a straightforward example of how to initialise the SDK, download the Node.js Scaffold sample app from GitHub.

  1. Once you have downloaded the SDK or sample app, go to the Apps tab and select the app you created in the previous steps.
  2. Select the "Client certificate" tab.
  3. Copy the snippet.
  4. Insert the snippet into into the Node.js project to initialize the SDK.

The client certificate code in your Node.js project should look something like this:

const HMKit = require('hmkit')

const hmkit = new HMKit('dGVzdM8GqScLvKy/EImRyejR5Ho/i1cFGcuU2yGjuwCtbRntVTRUQySPkIpY2b13yhTrmuk5I3yt8X4DqEMyZZ+NRRR+3Uwmmcs82r2tDPmoW6GJWGHJtTnJ/qIRcSXYBbkUfIsJPhdF91NPy5aM1JQV/cYGHEDH4mdUaXkUdyaMQLCa3yL6ALtUsDj7Vf7YQeiNweRny1RY', 'Ltx2fURBZdSWFSYc0EgbZoE3tnL1mqCEPZ5P1BuycyU=')

Send a Telematics Command

Once the emulator is open, fire away a Telematics command. For example, you can unlock the doors of the vehicle. Note that a "Vehicle is Sleeping" error will be returned if the emulator is closed.

If you see that the app lacks permissions, you will need to revisit step two of the "Create an App" section of this document and select the appropriate permissions for your telematics command.

Read more about Telematics

Auto API

Check out the Node.js code reference for Auto API for further details on how to use vehicle commands.

const response = await hmkit.telematics.sendCommand(
    hmkit.commands.EngineStartStop.getState(), // command helper function
    accessCertificate // access certificate
)

console.log('bytes:', response.bytes()) // [11, 0, 99, 1, 1, 0, 15, 1, 0, 1, 1, 2, 0, 8, 0, 0, 1, 111, 205, 24, 26, 34]
console.log('object:', response.parse()) // EngineStartStopResponse { status: { value: 'active', timestamp: 2020-01-22T11:51:46.466Z } }

Deployment to Heroku

When deploying your application to a Heroku environment, check the default Node.js version and specify another if necessary (specifying Node.js version in Heroku). At this time, Node.js v6 is the default and you may specify another in your package.json file.

Add this snippet to package.json:

{
  /**/
  "engines": {
    "node": "^8.4.0"
  }
}