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.
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.
- Go to the Develop tab, click the big plus (+) button and select Cloud App. Enter a name and continue.
- In the left section, select the permissions that your app needs under the "Permissions" tap. For the purporses of this tutorial, you will need to select the "Diagnostics" capability and then select "Get odometer" before pressing "save".
Note: Each permission must be manually added to each new app. - 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.
- Go to a carmaker workspace, click the big plus (+) button and select one vehicle to start. Enter a name and continue.
- You will find the vehicle capabilities listed to the left.
- 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.
- Once you have downloaded the SDK or sample app, go to the Apps tab and select the app you created in the previous steps.
- Select the "Client certificate" tab.
- Copy the snippet.
- 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=')
Link Vehicle and Authorise Device
Now, link the vehicle with the app in order to work with it in the emulator. Follow the next steps:
- Go back to your app details page in the Apps tab and click on the "Create link" button on the right side.
- Choose the vehicle you just created and link it to your app. The vehicle will be added to linked vehicles list, but you will see an alert icon between the app and the vehicle. That means that your Node.js app has not yet been authorised.
- Click on the alert icon and you will see an Access Token snippet that is unique to this link. Copy it.
- Insert the snippet into your project code and run the app.
- Click on the vehicle to launch the emulator. Now you can start using your app to interact with the vehicle's APIs.
Production mode
In order to get an Access Token for a production app, either the OAuth2 consent flow or the Fleet Clearance documentation should be followed.
The access token code in your Node.js project should look something like this:
const accessCertificate = await hmkit.downloadAccessCertificate('b55af95a-607c-47e8-ad37-5016a8beda61')
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"
}
}