smartdevicelink/sdl_javascript_suite

SmartDeviceLink library for applications developed in JavaScript

sdl_javascript_suite

SmartDeviceLink library for applications developed in JavaScript

Background details for creation of repository can be found in the SDL Evolution Proposal SDL 0235 - SDL JavaScript library. Initial implementation details can be found below.

Proposed solution

The solution is to create a common JavaScript library that offers a public proxy object to send and receive RPCs. The library also requires implementations of all the other layers required to package and frame the data and send it over a defined transport.

SDL library layers

Looking into the existing libraries, developed in Java and Objective-C, they contain the following superset of layers:

1. The High Level Interface is a work-in-progress developer friendly API with the purpose to provide a programming interface similar to mobile frameworks.
2. The Manager layer is the current programming interface that abstracts the heavy load of dealing with application lifecycle, screen, dealing with RPCs and many more.
3. The Proxy layer also known as RPC layer, is the lower level interface with the purpose of managing the connection to the remote endpoint and sending and receiving RPCs. The RPC specification of the mobile API is implemented in this layer.
4. The SDL Session layer is responsible for the lifecycle of service sessions for e.g. RPC/Bulk, video and audio. It packages application data and sends it to the protocol layer.
5. The SDL protocol layer is responsible for organizing the sending and receiving of frames as per the Protocol specification
6. The transport layer is the root level of SmartDeviceLink and therefore the most critical layer as it is responsible for the foundation of data transmission.

It is not realistic to develop a new SDL library that can provide the same set of features as the Android and iOS library all at once. Therefore it is important to focus on a "milestone 1" which includes the following fundamental elements:

Included tasks in this proposal

1. Proxy layer

Provide a Proxy class and implementations of all RPCs according to the RPC specification v5.1. As this specification is XML structured it makes sense to develop a code generator to export all the RPCs, structs and enums to usable code.

2. SDL Session layer and Protocol layer

In the first milestone the JavaScript library should support the RPC and Bulk service types for communication. Media and projection applications may not be supported in the first release.

An open source BSON libray developed in JavaScript should be used by the SDL JavaScript library. If there is no suitable 3rd party BSON library available, a new BSON library will be created according to the specification of bsonspec.org.

3. Transport layer

The first release should come with a base/abstract definition of the transport layer. Based on this definition a WebSocket Server transport described in Cloud App Transport Adapter should be implemented with this proposal. Additionally a TCP socket client transport should be implemented for development purposes. Both transports should be implemented for Node.js runtime.

Manager layer

The first managers that should be introduced in future proposals should be a lifecycle manager and the file manager. Other managers (screen manager etc.) should be added in future releases.

This proposal does not include a manager layer. Managers will be introduced via new proposals.

Promise based development

Just as the other existing libraries, the JavaScript library requires possibilities to perform async operations. JavaScript is very well capable of serving this task especially with using the Promise pattern.

There are many sources describing the Promise pattern with JavaScript and how it is used already in the native API and other libraries and frameworks. See Mozilla: Promise and You Don't Know JS - Promises

Project management

The JavaScript library will be open source and stored in a new smartdevicelink repository on GitHub called sdl_javascript_suite. The project maintainers will be responsible for maintaining and reviewing the code and the project.

The development should be done in JavaScript (not TypeScript) following ECMA-Script 2017. All the base source code should be developed using JavaScript standard built-in objects.

The transport related source code for Node.js can use Node specific libraries needed (like socket.io). This code should be stored in a separate folder from the base source code in the repository.

Building the Project

NodeJS, npm, and Python3 are required:

git submodule init
git submodule update
npm install
npm run build

The output will be in the dist folder. There is a vanilla JS and a NodeJS build, which can be placed into the corresponding example apps in the examples folder to test out the library.

sdl_javascript_suite's Issues

SdlPsm

Parses incoming bytes according to the protocol spec.

Create VanillaJS sample app

Expected Behavior

Create an example vanilla js app using the SDL library in the project.

The example app should register, display app icon, and perform a show command.

Node - Websocket Server

Feature Request

Per the original proposal, the library needs to have an included Websocket Server for the Node extension of the suite. This feature will likely include building out the base transport files.

[SDL 0279] Screen Manager Subscribe Buttons

Proposal: Screen Manager Subscribe Buttons

This proposal introduces a screen manager feature for developers to subscribe to hard buttons instead of sending subscribe / unsubscribe RPCs.

Review: smartdevicelink/sdl_evolution#936

Steering Committee Decision:

The Steering Committee voted to accept this proposal with revisions. The revisions will include implementing the alternative approach described in this comment from the author, as well as fixing the SDLSubscribeButtonHandler error as detailed in this comment from the author.

The proposal .md file was updated to reflect these revisions on 2/20/2020.

PerformAudioPassThru causes json unmarshaller to fail

When sending a valid RPC to core, it's not the response that is an issue, but the OnAudioPassThru notification comes in with no JSON payload. There isn't a validation check for the payload being empty.

App should unregister if the MinimumProtocolVersion is higher than the supported one by Core

The LifecycleManager does nothing with the minimum protocol version, but does check the minimum rpc version.
sessionListener.setOnProtocolSessionStarted is where the check should happen. If the set minimum protocol version is higher than the one received, then the connection process should not continue.

Complete the Session Layer

Create Node.js Sample App

Expected Behavior

Create an example Node.js app using the SDL JavaScript library classes.

The example app should register, display an app icon, and perform a show command.

[SDL 0283] Add Scrollable Message and Slider to Screen Manager

Proposal: Add Scrollable Message and Slider to Screen Manager

This proposal adds scrollable message and slider management to the screen manager API.

Review: smartdevicelink/sdl_evolution#949

Steering Committee Decision:

The Steering Committee voted to accept this proposal with the revisions included in this comment from the author.

The proposal .md file was updated to reflect these revisions on 3/23/2020.

SdlPacket

Create/Update SdlPacket.

[SDL 0282] Screen Manager Alert Manager

Proposal: Screen Manager Alert Manager

This proposal adds alert management (based on the Alert RPC) to the screen manager API.

Review: smartdevicelink/sdl_evolution#948

Steering Committee Decision:

The Steering Committee voted to accept this proposal with the following revisions:

• Use a builder pattern as described in this comment.
• Change SDLAlertAudioData to be a subclass of SDLAudioData.
• Change the audio data property and initializer to take an array to allow for multiple pieces of audio data.
• Clarify "if the error value is present, then the alert failed to appear or the user aborted it, if not, then the alert dismissed without error." within the inline documentation for presentAlert.

The proposal .md file was updated to reflect these revisions on 3/9/2020.

Add Video Streaming to Protocol Layer

Add the ability to request an video service (referred to as a NAV service type but the javascript sdk refers to it as simply an video service type), send raw packets using this video service, and end the individual video service without closing the entire session.

Update how the Screen Manager removes a graphic from a template

Bug Report

Currently, the screen manager API uploads a transparent image and uses that image name whenever the graphic needs to be removed from the template. This is not necessary as we can just use an "empty" Image in the graphic or secondaryGraphic field of a Show request. Below is an example of how to create an "empty" Image.

graphic:{ value:"", imageType:"DYNAMIC" }

Browser & Version Information

• Browser and Version: n/a
• SDL JavaScript Suite Module: n/a
• SDL JavaScript Version: 0.2.0 Beta
• Testing Against: n/a

Build Issue with Node

The node-specific files are not being used in preference to the files in the js folder with the same name.

setImageTypeSupported must expect an array

Bug Report

The setImageTypeSupported method in the ImageField RpcStruct currently expects a single FileType as input. However, this method should actually expect an array of FileType objects in accordance to the RPC Spec.

[SDL 0240] WebEngine support for SDL JavaScript

Proposal: WebEngine support for SDL JavaScript

This proposal is adding a new transport to the SDL JavaScript library to support (progressive) web apps to run on a WebEngine or a browser.

Review: smartdevicelink/sdl_evolution#767

Steering Committee Decision:

The Steering Committee voted to accept this proposal with the following revisions:

• When formatting locales in the manifest.json file, use standard (RFC 5646), and convert locale strings when necessary.
• Do not specify the location of the manifest's <script> tag placement within the proposal.
• All revisions included in this PR: https://github.com/smartdevicelink/sdl_evolution/pull/888/files

The proposal .md file was updated to reflect these revisions on 12/19/19.

Create SdlProtocolListener

Add JSDoc

Add documentation to already existing classes in the project so that methods are accounted for when running jsdoc

[SDL 0288] Screen Manager Play Audio

Proposal: Screen Manager Play Audio

This proposal adds a playAudio method (based on the Speak RPC) to the screen manager.

Review: smartdevicelink/sdl_evolution#962

Create MessageFrameAssembler

Update License to 2020

License file should be updated from "Copyright (c) 2019 SmartDeviceLink Consortium, Inc." to "Copyright (c) 2019 - 2020 SmartDeviceLink Consortium, Inc."

ESLint Configuration

Bug Report

Add ESLint configuration to help contributors make properly-formatted code contributions.

Reproduction Steps

N/A

Expected Behavior

IDEs (such as Atom IDE) find an ESLint configuration to evaluate against and provide errors/warnings when code is found to be out of compliance. Also provide a set of NPM scripts to be able to execute ESLint checks on-demand.

Observed Behavior

IDEs (such as Atom IDE) do not find an ESLint configuration to evaluate against and therefore do not provide errors/warnings about code style compliance. Additionally, no NPM scripts are present to run ESLint checks.

Browser & Version Information

N/A

Test Case, Sample Code, and / or Example App

N/A

Permission Manager

Bug Report

Create Permission Manager to give developers information about what permissions are permitted in the specific HMI level.

[SDL 0289] Support for Set Language Separately

Proposal: Support for Set Language Separately

This proposal provides support for updating to two separate languages.

Review: smartdevicelink/sdl_evolution#963

OemCustomVehicleData methods missing

Bug Report

Methods for OEM Custom Vehicle Data are missing from the generated Vehicle Data RPCs.

Expected Behavior

OEM Custom Vehicle Data methods should be added to the generator script to be included during the RPC generation process.

Coding Style Guideline Updates

"Acronyms should either be all uppercased or lowercased." This rule isn't currently being followed for class names like JsonRpcMarshaller SdlPsm. The class names are easy to read this way and so the rule should be removed from the guidelines. Proper camelcase, pascal case, and uppercase with underscores for constants should still be used.

[SDL 0272] JavaScript Suite SDL Manager

Proposal: JavaScript Suite SDL Manager

In a similar vein to this proposal, the goal is to introduce a manager layer to the JavaScript Suite, closely matching the Java Suite and iOS manager APIs. These manager classes are designed to abstract out complex flows and states for common tasks, such as file handling and displaying information to the screen.

Review: smartdevicelink/sdl_evolution#901

Steering Committee Decision:

The Steering Committee voted to accept this proposal with the revisions listed below:

• (Item 2) Pass an AppConfig instance into the SDLManager constructor. The SDLManager start() method can perform the basic validation checks prior to starting the LifecycleManager to ensure the minimum properties of an AppConfig are provided, as well as a ManagerListener being defined.
• (Item 3) Single-method listeners to be replaced with simple JavaScript-oriented callback functions.
• (Item 7) Promises should be returned by manager methods which ultimately send one or more RPCs resulting in a single response. Developers then have the freedom to decide if/how they would like to handle the resolution or rejection of the RPC response. 
• (Item 12) Remove getInternalInterface() in favor of utilizing the reference to the LifecycleManager

The proposal .md file was updated to reflect these revisions on 3/3/2020.

Update SdlProtocolBase with basic RPC functionality

SDL Manager

Bug Report

Create SDL Manager which will be used to surface the other manager layers to app developers.

Create JSON (De)Marshaller for RPCs

The JsonRpcMarshaller is responsible for converting messages to and from byte arrays and needs to be implemented before being able to sending and receiving RPC messages.

Ensure that the Managers' RPC listeners check the RpcType when being notified

The managers' RPC listeners only check the function ID and need to check that it matches a certain type.

RPC Struct and Messages Have Bad Keys

Bug Report

Some of the keys used in the rpc messages and structs are wrong. They either point to the wrong thing or something that does not exist.

Reproduction Steps

Create an RPC message or struct for one of the affected classes. Try to set and get affected variables. Observe that the variables are not set and fetched properly.

Expected Behavior

Should be able to use setters and getters.

Observed Behavior

Unable to set and get for some structs and messages.

Add Unit Tests For Basic Request, Response, and Notification RPCs

Cloud App Auth Token not set properly

When a Cloud App connects to SDL Core, the Auth Token from Core's policy table does not get set in the SDL Manager.

Apply Linter to Project

Bug Report

Now that we have a linter configuration, we should apply it to the entire project to standardize the syntax and use it for all future PRs.

Steps

1. Run eslint lib/*
2. Categorize all types of linter fixes and split them into their own PRs
3. Review and approve each PR created

Node WebSocket Server Custom Transport Fixes

Bug Report

Fix the Node.js WebSocket Server Transport to utilize the Custom Transport class, then verify the Node.js example app still works with Manticore.

Add Audio Streaming to Protocol Layer

Add the ability to request an audio service (referred to as a PCM service type but the javascript sdk refers to it as simply an audio service type), send raw packets using this audio service, and end the individual audio service without closing the entire session.

Connection doesn't get disposed of properly when the app is finished

Bug Report

For client applications specifically, such as TCP client apps or WS client apps, when the sdlManager's dispose method is invoked, the underlying transport connection does not shut down.

When dispose is called, the TCP node app should have no more running process, and for the WS app in the browser, you should be able to see in the network tab for that connection that it has closed.

Create BinaryFrameHeader class

Use the New Lifecycle Managers for the Example Apps

Expected Behavior

The node and vanilla JS app should use the lifecycle manager once it's ready to simplify the complexity of their functionalities.

Make Variables Private when Possible

Any method that isn't a getter/setter, and wouldn't be used outside of the class, should be made as a private method or member.

Remove RPC_SPEC numeric enum generation / define custom numeric enums

Bug Report

There was a big internal discussion about so-called "numeric" enums, which are enum values in the RPC spec that have a value attribute with a numeric value. The conclusion was that Core is capable of receiving Strings or Integers but will only send the string. This means that, depending on the context, we may need to support the string value or the integer value.

There are basically three enums that support value with an integer: LightName, messageType[sic], and PredefinedWindow. messageType is only used in the protocol binary header as an integer, not a string. PredefinedWindow's value is only used in other RPC_SPEC parameters that ask for an integer value. Its string value is never used. LightName appears to only ever be used as a string value.

For this reason, the iOS and Java_Suite generators will now only create the String enums. To align with the iOS and Java Suite generators, the generated code will then have to be altered as necessary to support integers. This could be either by replacing the string enums that need integer enums with integer equivalents, or by adding integer equivalents into the string enum class.

Create SystemCapabilityManager

An implementation of the SCM is needed

[SDL 0234] Proxy Library RPC Generation

Proposal: SDL 0234 - Proxy Library RPC Generation

This proposal adds automatic RPC generation for iOS and Java from the XML spec via a python script.

smartdevicelink/sdl_evolution#741

Steering Committee Decision:

The Steering Committee voted to approve this proposal with the following revision: there will be parsing code in each repository, and the rpc spec will be a submodule that pins which rpc spec will be used in each version of the library.

Revisions were made on 2019-06-10

Managers should hit a READY state before HMI is full

Bug Report

The permission manager is stuck getting to a READY state until HMI FULL is received, when it should be ready before then. Without this working, app icons cant be set on connection, and the app has to be set to FULL first

[SDL 0274] Add preferred FPS to VideoStreamingCapability

Proposal: Add preferred FPS to VideoStreamingCapability

This proposal extends SDL video streaming feature by adding preferred FPS to VideoStreamingCapability, so that frame rate of video streaming can be adjusted per OEM.

Review: smartdevicelink/sdl_evolution#913

Steering Committee Decision:

The Steering Committee voted to accept this proposal with revisions. The revisions will include the items listed in this comment from the author.

The proposal .md file was updated to reflect these revisions on 2/10/2020.

[SDL 0246] Add App Services to HMICapabilities

Proposal: Add App Services to HMICapabilities

SDL-0167 introduced the App Services functionality. It included a new capability, however that capability was not included into the HMICapabilities struct as all other system capabilities have been.

Review: smartdevicelink/sdl_evolution#807

Create FileManager

Basic FileManager implementation is needed.

Manage Multiple Connections as Isolated Sessions

Bug Report

Currently, when multiple Core instances connect to an SDL JavaScript WebSocket Server, SDL payloads (responses, notifications) are sent to all connected Core clients instead of the individual Core client responsible for the original request/subscription.

Expected Behavior

Each connection from Core should be treated as an isolated session to avoid cross-contamination of RPC responses/notifications, which would lead to unexpected behavior.

Test Case, Sample Code, and / or Example App

The hello-sdl Node app exemplifies the problem.

Address Example App Review Feedback

Bug Report

Address TODO feedback left in #44 and #46