Permalink
Switch branches/tags
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
361 lines (269 sloc) 21.3 KB

IBM IoT Connected Vehicle Insights - Fleet Management Starter Application

The Fleet Management Starter Application for the IBM® IoT Connected Vehicle Insights SaaS offering demonstrates how quickly you can build an app on IBM Cloud to manage and monitor a fleet of vehicles in real time.

Overview

The Fleet Management Starter Application uses the IBM IoT Connected Vehicle Insights SaaS offering together with IBM Cloud services to provide a sample solution for fleet operation management and personnel. By using the application, you can easily track and view the following information:

  • Availability of a fleet of cars on a map
  • Location of vehicles
  • Overall health of the entire fleet
  • Health diagnostics and conditions of a specific vehicle in the fleet
  • Condition of vehicles by order of severity or risk
  • Event history for the entire fleet
  • Event history for a specific vehicle in the fleet

The Fleet Management Starter Application uses the following IBM Cloud services:

Prerequisites

To deploy and use the Fleet Management Starter Application, you need an instance of IBM IoT Connected Vehicle Insights that is deployed and running on either IBM SaaS.

Deploying the app

Deploy the Fleet Management Starter Application on IBM Cloud either automatically or manually, as outlined in the following instructions.

Automatically deploy the starter app on IBM Cloud

To automatically deploy the Fleet Management Starter Application on IBM Cloud, click Deploy to IBM Cloud.

The automatic deployment option creates an instance of the app and the required IBM Cloud services, and also binds the services to the starter app automatically. After the automated deployment, complete the following steps to configure the app to manually to connect to your IBM IoT Connected Vehicle Insights SaaS service.

  1. Open the IBM Cloud dashboard in your browser.
  2. To stop the app, click ACTIONS > Stop App.

Next: Go to Connecting to IBM IoT Connected Vehicle Insights service.

Manually deploy the starter app on IBM Cloud

To manually deploy the Fleet Management Starter Application on IBM Cloud, complete all of the following steps:

  1. Log in to IBM Cloud. If you do not have an existing IBM Cloud account, click Register and follow the instructions to create an account.
  2. Download and install the Cloud-foundry CLI tool.
  3. Clone the Fleet Management Starter Application to your local environment by using the following console command:
git clone https://github.com/ibm-watson-iot/iota-starter-server-fm-saas.git
  1. Change to the directory that you created.
  2. Edit the manifest.yml file and change the values of <name> and <host> to something unique. <host> must be same with postUrl in gateway.properties.
applications:
       :
  host: iota-starter-server-fleetmanagement
  name: iota-starter-server-fleetmanagement
  memory: 512M
  path: .
  instances: 1
       :

Note: The host value is used to generate your application URL, which is in the following syntax: <host>.mybluemix.net.

  1. Install the NPM package by using the following command. The installer observes the dependencies that are specified in your package.json file.
$ cd ./webclient
$ npm install
  1. Convert TypeScript to JavaScript:
$ npm run tsc
$ npm run gulp
$ cd ..
  1. By using the command line tool, connect to IBM Cloud and log in when prompted:
$ cf api https://api.ng.bluemix.net
$ cf login
  1. Create an instance of the Cloudant NoSQL DB service in IBM Cloud:
$ cf create-service cloudantNoSQLDB Lite FleetCloudantDB
  1. Push the starter app to IBM Cloud by using the following command:
$ cf push --no-start

Important: When you run the push command, you must include the --no-start option as you must complete further steps manually before you start the app.

Result: Your very own instance of the IBM IoT Connected Vehicle Insights - Fleet Management Starter Application is now deployed on IBM Cloud.

Deploying custom plugins to your IBM IoT Connected Vehicle Insights instance

To run the Fleet Management Starter Application with your IBM IoT Connected Vehicle Insights instance, the following two custom plugins must be deployed to your IBM IoT Connected Vehicle Insights instance. The source code of the plugins is contained in plugins folder under the Fleet Management Starter Application repository.

Plugin Component Description
HttpActionNotifyClient Vehicle Data Hub (VDH) A VDH plugin that accepts sendCarProbe requests from simulated vehicles and POSTs affected events and notified messages to the Fleet Management Starter Application.
FleetAlert Agent A rule plugin that calculates fuel level from fuel tank capacity of a vehicle and remaining fuel in received probe. A fuel alert rule estimates the value to generate a fuel warning to be notified to the Fleet Management Starter Application.

To build and deploy the plugins, complete the following steps:

Prerequisites

  1. The IBM IoT Connected Vehicle Insights Plugin Deployment Tool must be installed on your IBM IoT Connected Vehicle Insights SaaS instance. Contact the system administrator for your IBM IoT Connected Vehicle Insights SaaS service to make a request to install it.
  2. The IBM IoT Connected Vehicle Insights Plugin Development Tool must be installed on your eclipse IDE, as outlined in the IBM IoT Connected Vehicle Insights Plug-In Programmer's Guide. To get access to the guide and the tool, contact your IBM IoT Connected Vehicle Insights system administrator.
  3. The Fleet Management Starter Application Git repository must be downloaded on your local environment. If you need to download the repository, you can clone it by using the following console command:
    git clone https://github.com/ibm-watson-iot/iota-starter-server-fm-saas.git
    

Import custom plugin projects to your eclipse IDE

  1. Launch the eclipse that contains IBM IoT Connected Vehicle Insights Plugin Development Tool.
  2. Open Git perspective (Window > Perspective > Open Perspective > Other...).
  3. From the Git Repositories view, click Add an existing local Git repository. Alternatively, you can also clone the repository by selecting Clone a Git repository.
  4. Specify a directory that contains the Fleet Management Starter Application Git repository.
  5. Select the Fleet Management Starter Application Git repository and click Finish.
  6. Right click the added repository on Git Repositories view and select Import Projects....
  7. Select Import existing Eclipse projects and click Next.
  8. Select FleetAlert and HttpActionNotifyClient and click Finish.

Export custom plugin jars

  1. Open Java perspective (WIndow > Perspective > Open Perspective > Other...) in your eclipse.
  2. Right click the HttpActionNotifyClient project in Package Explorer view and select Export....
  3. Select Java > JAR file and click Next.
  4. Input a file name in the JAR file field and click Finish.
  5. In the same manner, export the FleetAlert project as a JAR file.

Update a VDH configuration file (gatway.properties)

  1. Download a copy of the gateway.properties file that you deployed on the VDH server by using IBM IoT Connected Vehicle Insights Plugin Deploy Tool.
  2. Open the gateway.properties file with a text editor.
  3. Increment client.num in the gateway.properties file.
  4. Insert the following two lines before the DefaultHTTPClient client definition.
    client.client1=com.ibm.mobility.sample.http.HttpActionNotifyClient
    client.client1.protocol=http
    
  5. Renumber all the existing client definition keys so that they do not conflict with each other, for example:
    client.client2=com.ibm.mobility.autodrive.client.def.DefaultHTTPClient
    client.client2.protocol=http
    client.client2.agent=SM_API
    
  6. Insert the following client unique properties:
    HttpActionNotifyClient.postUrl=https://<your-iota-starter-fleetmanagement>.mybluemix.net
    HttpActionNotifyClient.postUser=starter
    HttpActionNotifyClient.postPassword=Starter4Iot
    
    1. For postUrl, replace the example URL with your Fleet Management app URL.
    2. If you modified the default postUser and postPassword credentials, replace the values that are specified in the properties file.
    3. Save the changes and close the editor.

A fragment of the gateway.properties file exists under conf folder of the HttpActionNotifyClient project. You can copy contents from the file.

Deploy custom plugins to IBM IoT Connected Vehicle Insights

  1. Deploy exported HttpActionNotifyClient jar and updated gateway.properties to a VDH server using IBM IoT Connected Vehicle Insights Plugin Deploy Tool.
  2. Deploy export the FleetAlert jar to an Agent server.
  3. Restart IBM IoT Connected Vehicle Insights components using IBM IoT Connected Vehicle Insights Plugin Deploy Tool as needed.

Connecting the app to your IBM IoT Connected Vehicle Insights service

After deploying the app on IBM Cloud, you must configure the app to connect to your IBM IoT Connected Vehicle Insights SaaS service instance.

Configuring IBM IoT Connected Vehicle Insights endpoints and credentials

{: #config_endpoints} To connect to your IBM IoT Connected Vehicle Insights service instance, the starter app reads the REST API endpoints and credentials from an environment variable on IBM Cloud. Configure the environment variables as follows:

  1. Open the IBM Cloud dashboard in your browser.
  2. Open the IBM IoT Connected Vehicle Insights service.
  3. Select Runtime tab at the left navigation bar.
  4. Click Environment variables.
  5. Add the following environment variable:
USER_PROVIDED_VCAP_SERVICES = <endpoint definition in JSON format>

Define the endpoints in the following JSON format. Note that you must remove any line breaks that are at the end of each line to set to the environment value on IBM Cloud.

{
    "iotforautomotive": [
        {
            "credentials": {
                "api": <IBM IoT Connected Vehicle Insights endpoint>,
                "username": <user name>,
                "password": <passsword>,
                "maximo": {
                  "orgid": <organization for IBM IoT Connected Vehicle Insights>
                  "classificationid": <classification for Vehicle Data>
                  "username": <user name for Maximo API >,
                  "password": <passsword for Maximo API >
                }
            }
        }
    ]
}

To obtain the correct values, contact your system administrator.

Key Description of Value
api A URL to call the REST API for IBM IoT Connected Vehicle Insights, which must end with a forward slash character (/)
username User name for accessing the Vehicle Data Hub (VDH) and other IBM IoT Connected Vehicle Insights endpoints
password Password for accessing the VDH and other IBM IoT Connected Vehicle Insights endpoints
maximo/orgid IBM IoT Connected Vehicle Insights Organization specified in IBM Maximo Asset Management
maximo/classificationid Classification for vehicle data defined in Maximo Asset Management
maximo/username User name for accessing the Maximo Asset Management API
maximo/password Password for accessing the Maximo Asset Management API

(Optional) Securing the connection to the IBM IoT Connected Vehicle Insights service

The IBM Secure Gateway service provides secure connectivity and establishes a tunnel between your IBM Cloud organization and the remote location that you want to connect to. Before you use the Secure Gateway service, contact your IBM IoT Connected Vehicle Insights system administrator. For more information, see Secure Gateway.

Configuring authentication

To secure the app, authentication is enabled by default for the IBM IoT Connected Vehicle Insights - Fleet Management Starter Application. The default user credentials are as follows:

User name Password
starter Starter4Iot
  • To change the user name or password that is used by the app, edit the values that are specified for the APP_USER and the APP_PASSWORD environment variables.

  • To remove authentication, set both the APP_USER and APP_PASSWORD environment variables to 'none'.

Starting the app

  • To start the Fleet Management Starter Application, open the IBM Cloud dashboard and start the app.

Congratulations! You are now ready to use your own instance of the IBM IoT Connected Vehicle Insights - Fleet Management Starter Application. To connect to the app, enter the following URL in your browser: http://<host>.mybluemix.net in your browser.

(Optional) Connecting to an OBDII dongle that is plugged in to your car

The starter app also provides a mobile app to connect to an OBDII dongle plugged in to your car. The mobile app sends data from an OBDII dongle to the Fleet Management Starter Application through the Watson IoT Platform service and you can see the data in the app. Complete the steps below to enable this optional feature.

Bind the Watson IoT Platform service to the app

  1. Open the IBM Cloud dashboard in your browser.
  2. Open the IBM IoT Connected Vehicle Insights service.
  3. Select Connections tab at the left navigation bar.
  4. Click Connect New.
  5. Select IBM Watson IoT Platform service, and then click Create to bind the service.

Create a device type for your device

When you start the OBDII Fleet Management App for the first time, your device is automatically registered to the Watson IoT Platform service with the default device type, which is OBDII. Create a device type for your device by completing the following steps:

  1. Open the Watson IoT Platform dashboard on IBM Cloud.
  2. Click Device.
  3. Click Device Types.
  4. Click +Create Type.
  5. Click Create device type.
  6. In the Name field, enter 'OBDII'.
  7. Leave the other fields as default and click Next at the bottom right until a device type is created.

Set up the OBDII Fleet Management App

To build and install the OBDII Fleet Management App on an Android phone, see the following repository.

After deploying the Fleet Management Starter Application, start OBDII Fleet Management App on your phone.

Connect the device to the IBM IoT Connected Vehicle Insights service

When you start the OBDII Fleet Management App for the first time, your device is registered automatically to the IoT Platform service that you have specified in the mobile app, and a corresponding vehicle is created automatically when you connect your device to the IoT Platform.

Now that your device is connected to the Watson IoT Platform, go to the Map or Car Status page in the app and see the status.

If you no longer need a device, go to the Watson IoT Platform dashboard and delete your device manually. After you delete a device, update the vehicles in the IBM IoT Connected Vehicle Insights service, as follows:

  1. Open the Fleet Management Starter Application on your browser.
  2. On the left navigation bar, click Vehicle.
  3. On the top right side of the page, click Sync with IoT Platform.

A vehicle corresponding to deleted device must be removed from a table. Also, if you have added a device to the Watson IoT Platform manually, the vehicle is added to the table.

Reporting defects

To report a defect with the IBM IoT Connected Vehicle Insights - Fleet Management Starter Application, go to the Issues section section.

Troubleshooting

To debug problems, check the IBM Cloud app logs. To view the logs, run the following command from the Cloud Foundry CLI:

$ cf logs <application-name> --recent

For more information about how to troubleshoot your application, see the Troubleshooting section in the IBM Cloud documentation.

Privacy Notice

The IBM IoT Connected Vehicle Insights - Fleet Management Starter Application includes code to track deployments to IBM Cloud and other Cloud Foundry platforms.

For each instance that you deploy, the following information is sent to a Deployment Tracker service on each deployment:

  • Node.js package version
  • Node.js repository URL
  • Application Name (application_name)
  • Application GUID (application_id)
  • Application instance index number (instance_index)
  • Space ID (space_id) or OS username
  • Application Version (application_version)
  • Application URIs (application_uris)
  • Cloud Foundry API (cf_api)
  • Labels of bound services
  • Number of instances for each bound service and associated plan information
  • Metadata in the repository.yaml file

This data is collected from the package.json and repository.yaml file in the sample application and the VCAP_APPLICATION and VCAP_SERVICES environment variables in IBM Cloud and other Cloud Foundry platforms. This data is used by IBM to track metrics around deployments of sample applications to IBM Cloud to measure the usefulness of our examples, so that we can continuously improve the content we offer to you. Only deployments of sample applications that include code to ping the Deployment Tracker service will be tracked.

Disabling deployment tracking

You can disable the Deployment Tracker service by removing require("metrics-tracker-client").track(); from the beginning of the app.js server file.

Providing feedback to IBM

Thank you for using our IBM® IoT Connected Vehicle Insights SaaS service and starter apps. As well as providing samples to help you get started, we'd like to know what you and your users think about our service offering.

The IBM IoT Connected Vehicle Insights Fleet Management starter application sample also includes the Medallia Net Promoter Score (NPS) widget code, which you can choose to deploy with the apps that you develop to integrate with the service.

The Net Promoter Score widget

The NPS widget provides a mechanism for you and your app users to rate your overall experience with the IBM IoT Connected Vehicle Insights service and to provide specific feedback comments to help us to continually improve the quality of the service offering and to increase your satisfaction. When you build an application by using our sample code, the NPS widget is automatically included in your app and provides the following user interface for providing feedback to IBM:

NPS Widget

When you or your app users rate the IBM IoT Connected Vehicle Insights service by completing the survey in the NPS widget, the rating score, feedback comments, and customer ID are automatically submitted back to IBM.

Disabling the NPS widget

By default, when you build an app by using the Fleet Management starter app sample code that is in this repository, the NPS widget is enabled. If you would like to remove the NPS widget from the user interface of your apps, complete the following steps:

  1. In this repository. go to the /webclient folder.
  2. Edit both the index.html and index-prod.htmlfiles and remove all of the code from <!-- NPS Widget BEGIN --> to <!-- NPS Widget END -->.
  3. Save your changes.

More information about the NPS widget

The IBM NPS widget is produced in partnership with Medallia. For information about the widget and the data that it collects, see Privacy Policy - Medallia.

Useful links