GM Dev Client

Turn your compatible GM vehicle into an app testing platform with GM Dev Client
 

 

 

 

GM Dev Client is a developer application with the ability to host a guest application that is being run in the GM Emulator. It allows developers to use a production vehicle to run their application on actual hardware. GM Dev Client is intended for developmental and testing purposes, and is not suitable as a medium for bypassing App Shop or permanently loading any application into the system. Guest applications are not copied to the vehicle; they are requested from the Emulator over the vehicle's WiFi connection and are unavailable as soon as the Emulator is disconnected from the system.

 

Getting Started

 

How to use GM Dev Client

In order to use GM Dev Client, it must be able to connect to a computer running the NGI Emulator. Both your vehicle and computer should be connected to the same WiFi Hotspot before proceeding.

Each time you launch GM Dev Client you will be presented with its Terms and Conditions for use. Acceptance does not carry over from session to session and you'll need to re-accept the conditions every time you want to use GM Dev Client.

To host a guest application in the GM Dev Client it must first be running in the Emulator. Run ngi serve to launch your application in the Emulator and note the External IP Address (without port) reported in your terminal:

NGI: Mock vehicle started on  3030

NGI: [BS] Proxying: http://localhost:3002
NGI: [BS] Access URLs:

NGI:  --------------------------------------
NGI:        Local: http://localhost:3000
NGI:     External: http://192.168.22.56:3000
NGI:  --------------------------------------
NGI:           UI: http://localhost:3001
NGI:  UI External: http://192.168.22.56:3001
NGI:  --------------------------------------

On the settings page you can configure GM Dev Client to connect to the External IP address (NOT UI EXTERNAL). Type in your IP address (192.168.22.56 from the example above), making sure to leave out the port and protocol. Press test to test the connection - green means go.

Returning to the main page, select Start to begin hosting your application.

 

Development Guide

GM API

The GM API will be available to any application hosted in GM Dev Client. See our /ngi/docs for details.

Vehicle information

Your guest application will also have access to all of the vehcile's live signals. To your application there is no difference between being hosted and being installed in terms of sensor and signal availability. The mocked signals in the Emulator will not affect the signals seen by a Dev Client hosted app.

Driver Distraction

GM Dev Client is perfect for developing and testing the implementation of driver distraction and network availability logic in your application. GM's first priority is to the driver safety, and in order to take full advantage of this you'll need two people - one to drive and one to perform application testing. Without a passenger present GM Dev Client's own driver distraction lockouts will appear and override your app's driver distraction logic, if present. If that occurs you can either quit GM Dev Client or put the vehicle in Park to continue development and testing.

GM Dev Client will allow you to continue development while driving if it detects a passenger and all front seatbelts are buckled. The driver lockout will allow the passenger to accept responsibility for development during driving. Once accepted, you won't see GM Dev Client's lockout again until the seatbelts are unbuckled, the passenger leaves, or you exit GM Dev Client.

Remote Debugging

You can inject a remote debugger into your application by opening the "UI External" URL in your web browser (http://192.168.22.56:3001 in our example). The Weinre remote debugger is similar to your browser's developer tools. It can be used to monitor and utilize the console loge, inspect DOM elements, and observe network requests.

  • Click on the Remote Debug tab
  • Enable Remote Debugging, and click to open the Weinre remote debugger
  • Once Weinre has been loaded, ensure that the external url is selected.

 

 

Requesting Access

Access to GM Dev Client is currently limited to developers that can provide the following information:

  • A VIN from a Compatible Vehicle (see below)
  • Proof of vehicle ownership or owner consent
  • A functioning application that is ready for testing

To request access, please send an email with the above details to Octavio Fabbri

Vehicle Compatibility

The following 2017 or later Chevy, Buick, GMC or Cadillac vehicle with with App Shop are capable of downloading and running 3rd party developed apps and can perform testing with GM Dev Client:

ModelYearBrandTrim
2017BuickLacrosseAll
2017BuickRegalAll
2017BuickEnvisionAll
2017GMCCanyonSLE
2017GMCSierraSLE/SST/DENALI
2017GMCAcadiaAll
2017GMCYukonSLE/SST/DENALI
2017CadillacATSAll
2017CadillacXTSAll
2017CadillacEscaladeAll
2017ChevyMalibuPremier
2017ChevyCamaro2LT/1SS/2SS
2017ChevyCorvetteAll
2017ChevyTahoeAll
2017ChevySuburbanAll
2017ChevyColoradoLT/Z71
2017ChevySilveradoLT/LT Z71/LTZ/ LTZ Z71/High Country
2017ChevyVoltAll
2018CadillacCT6All - 10" NGI
2018ChevyEquinoxPremier

Updated July 20, 2017
 

Application for Testing

When your application is ready for vehicle testing and you are ready to request access to GM Dev Client, package your application by running ngi package. The resulting '.ngi' file is what you will send to GM for consideration for receiving access to GM Dev Client.

Generally speaking, apps that are in a proof-of-concept phase are ok to submit, and most companies in our early access program were able to generate an app of this quality in 1-2 weeks.

 

Known Issues with v1.0.1

  1. Local Audio (e.g. mp3s contained within the application directory) may not play.
  2. Application (Dev Client) will quit when focus is lost (hitting home button). This is intentional behavior that will be modified in a future release.
  3. The Dev Client only supports single page applications, multipage apps are not yet supported. This behavior feels like a bug, but matches GM internal usability and certification guidelines. For example, going from index.html to banana.html does not work; index.html to index.html#taco will work fine).

 

Limitations

When GM Dev Client hosts your application it doesn't exist locally on the vehicle. It is served via the Emulator, which GM Dev Client taps into to host your application. This has several implications for your application.

  1. Private API access is prohibited. GM Dev Client is not suitable for developing an application that relies on private APIs, as GM Dev Client itself doesn't have access to them.
  2. There may be some latency. Because GM Dev Client hosts guest applications over a network, there will be increased latency when loading content as compared to a production installation, specifically during application startup.
  3. Best suited for single-page-applications. GM Dev Client is best suited for a SPA rather than multi-page application. This is also true of platform itself; page transitions often cause momentary blank-screens, which detract from the user experience.

 

FAQs

Q. I'd like to debug my application that's being hosted. A. Weinre works well for remote debugging of your app. If you have a separate install of weinre, want to debug ONLY the hosted application (not the in-Emulator instnace of your application), and prefer not to use the Remote Deugging steps aboce, then place the following code in the <head> tag of your application. This script expects a Weinre server running on port 80 at the specificed ip address.

<script id="me">  
;(function() {
    var ip = "CHANGE_TO_YOUR_EXTERNAL_IP"
    if (document.domain === ip) {  // Modify to match your IP address
      var me = document.getElementById('me');
      var weinre = document.createElement('script');
      weinre.setAttribute('src', 'http://'+ip+'/target/target-script-min.js');
      me.parentNode.insertBefore(weinre, me.nextSibling);
    }
  })();
</script>


Q. I changed some files and my application reloaded. Now it's not running. A. This issue arises when your single page app does not handle stateful routing. If save a file while on a page like /#!/mymessages/inbox, GM Dev Client will revisit this full url after app compilation and reload. If your application does not save or handle stateful routing from outside the entry point, then /#!/mymessages/inbox may not display correctly. Closing and restarting your app should allow you navigate back to the layout you are testing and see changes.

Q. My application used the writeFile API, where did that file end up? A. The guest applications that GM Dev Client hosts are sandboxed within GM Dev Client itself. All files are wiped clean when your app is unloaded. If you wish to persist the information you're writing to disk you will need to offboard it before exiting your application (i.e. POST that information to an external server).

Q. I was booted back to GM Dev Client in the middle of testing my application. A. GM Dev Client will return you to the main page if it loses connection to the Emulator. Please check your network connections. Closing the Emulator will send a disconnect signal and return you to GM Dev Client right away. If the network is disabled GM Dev Client will retry the connection. It may take up to 30 seconds to return to GM Dev Client after a network disconnect event.

Q. If I turn the vehicle off while hosting an application, will it be available when the vehicle is turned on again? A. No, the session within GM Dev Client will have been severed during power cycle and will need to start fresh.

Q. When I run the same URL in my web browser, my application does not work. A. Your application is dependent on the GM API, which is only available through the Emulator or within GM Dev Client. In running your application in any other context, the window.gm object will be undefined.

Q. Some of my css/images (fonts, etc.) render correctly in the Emulator but not GM Dev Client A. The vehicle's filesystem is case-sensitive, but your host machine may not be; check your filenames!

Q. I am unable to connect via wifi. A. If you have a firewall running, ensure that access to node and/or the requisite ports (3000, 3030) are open. You may be able to get away with simply allowing inbound connections on the network profile. In Windows 7, for example:

  1. Open firewall settings
  2. Select firewall properties
  3. Navigate to the public network profile
  4. Select to allow inbound connections.