Note: This requires you to use Ubuntu 18.04 or 20.04.
Clone the SDL Core repository and follow the setup instructions for the project. After the project is built, run an instance of SDL Core in your terminal.
- nvm
- chromium-browser
- python3 and pip
- ffmpeg
- ffmpeg-python
- pyopenssl
sudo apt install chromium-browser ffmpeg python3 python3-pip -y
python3 -m pip install ffmpeg-python pyopenssl
Check out nvm on github to learn how to install and use nvm!
Once SDL Core is running, follow these steps to set up the Generic HMI.
First, clone this repository. Once cloned, you can initialize the git submodules in this project by running the following commands:
cd generic_hmi
git submodule init
git submodule update
Alternatively, you can clone this repository with the --recurse-submodules flag.
The build directory is not included in the github repository. In order to use the generic HMI you must build the application yourself.
Note: These instructions are written for Node version 12
Install NVM and use node version 12
nvm use 12
Install dependencies (you might need to clean the node_modules folder):
npm install
Build the project:
npm run build
Note: This command must be run before launching the HMI in the browser.
After running the build command, you can launch the Generic HMI in a web browser:
chromium-browser generic_hmi/build/index.html
NOTE Chromium is the only supported and tested browser. Browsers built on top of Chromium (Google Chrome) should work but are not officially supported.
The generic_hmi includes an additional backend component that is required for some features, such as in-browser video streaming, policy table updates using the vehicle modem and accessing the webengine app store.
- Run
deploy_server.shin the root folder - Start and run the HMI normally
The backend connection status is indicated by an icon in the hmi settings page (top-right).
The icon will contain a check mark if the backend server is connected/cross if the backend server is disconnected.
Clicking on the icon will display a prompt allowing the user to set the url for the backend. Once the URL is set, the HMI will attempt to re-connect to the backend server.
The following features can be used in the hmi if the backend server is connected.
Select the PTU using in-vehicle modem checkbox to enable the feature
Start a video service from the SDL app. The video stream should start in the browser.
Video streaming also requires you to have all the aforementioned dependencies installed.
The app store can be accessed from the hmi settings page. Clicking on any of the listed webengine apps will allow you to download the webengine app.
The main third-party technologies we use to develop this HMI are React, React-Redux, and React-Router. The HMI component of SDL is responsible for processing and responding to RPCs which are received from a connected SDL Core instance.
This is the main entry point for the entire application. It sets up the routes and highest level components in the React app. Once the application is loaded, it attempts to connect to an instance of SDL Core.
This is the main path to all things SDL related. The Controller routes RPCs coming from SDL to sub-controllers so that they can be handled, and responds to SDL. Sub-controllers all implement a handleRPC() function. The handleRPC function returns true if the Controller should respond with a generic success to SDL, return false for a generic false, return an object with a key of rpc to respond with a custom RPC, and return null if the Controller should not respond (such as in the case of incoming notifications from SDL). The Controller also implements a sanitize function which can be used to manipulate RPCs before they're sent off to a sub-controller to be handled.
Implementing an RPC is the main activity when developing this HMI as it related to communicating with SDL Core. There are three basic behaviors that can be implemented
- An RPC comes in from SDL Core which changes some information displayed to the user in a view (Implementing Requests)
- The user takes action on an element in the React Application which generates a message to SDL Core (Sending messages to SDL Core)
- An RPC comes in from SDL Core which forces the current view in the React Application to change (Changing the router history)
First, add a case statement to the appropriate Sub-Controller. If the RPC is named UI.something, the appropriate sub-controller is the UIController. The case statement should dispatch a method to the store that you'll define shortly. Import that method name from actions at the top of the Controller. Head over to actions.js, add a new string to the Actions const and export a new method of the same name which returns an object containing the same parameters you passed and a type property which is the new Action you defined. In reducers.js you can now add a case statement for the Action name you created. Return a new state object based on the parameters passed into the action from the Controller. This state will be used in a container to send the appropriate information to a React Component. For more information about actions and reducers check out http://redux.js.org/docs/basics/index.html. Example of all this below.
// UIController.js
import {
show // Importing the new action for use with store.dispatch
} from '../actions'
...
handleRPC(rpc) {
...
case "Show":
store.dispatch(show( // dispatching the action with the needed info
rpc.params.appID,
rpc.params.showStrings,
rpc.params.graphic,
rpc.params.softButtons
))
return true
...
// actions.js
export const Actions = {
SHOW: "SHOW" // Defining the new type
}
...
export const show = (appID, showStrings, graphic, softButtons) => { // exporting the show action
return {
type: Actions.SHOW, // Specifying the new type
appID: appID,
showStrings: showStrings,
graphic: graphic,
softButtons: softButtons
}
}
// reducers.js
function ui(state = {}, action) {
switch (action.type) {
case Actions.SHOW: // implementing the reducer, you can do this in any of the functions that are to be reduced into state
var newState = { ...state } // Copy over the old state
var app = newState[action.appID] ? newState[action.appID] : newAppState() // Find the app specified by the action that we're changing state for or create a new one
newState[action.appID] = app // set it back in case we created a new one
if (action.showStrings && action.showStrings.length > 0) {
app.showStrings = action.showStrings // Change show strings if they changed
}
if (action.graphic) { // Add the graphic to the state if it exists
app.graphic = action.graphic
}
if (action.softButtons && action.softButtons.length > 0) { // Change soft buttons if they changed
app.softButtons = action.softButtons
}
return newState // self explanatory
...At this point, you'll need to think about what component needs the information in the React application which you've just added to the state. In the example above, the information in the Show RPC is used in the MediaPlayerBody component as MetaData. So create a file for the container which will be hooked up directly to the React Component which needs the information about show. Below is a commented version of the Metadata container which parses out the useful information added to the state by the Show RPC for use in the React Component.
// Metadata.js
import { connect } from 'react-redux' // so we can connect this container with the appropriate react component
import MediaPlayerBody from '../MediaPlayerBody' // this is the React component we're connecting it which will use the props we create off the state
const mapStateToProps = (state) => { // a function you always have to implement
var activeApp = state.activeApp // The active application in the react component
var metadata = state.ui[activeApp] // The UI metadata for that application (we created all this in reducers.js when we implemented Actions.SHOW)
if (metadata === undefined) return {} // Do nothing if there is no metadata yet
var props = { // Default mainfields for the react component
mainField1: null,
mainField2: null,
mainField3: null
}
metadata.showStrings.map ((textField) => { // Iterate all the strings added by the show
switch (textField.fieldName) { // Each textField has a fieldName which is its type
case "mainField1": // Map types to props that'll be used by the Component
props.mainField1 = textField.fieldText
break
case "mainField2":
props.mainField2 = textField.fieldText
break
case "mainField3":
props.mainField3 = textField.fieldText
break
}
})
// If there is a graphic, add it to the props
props.graphic = metadata.graphic ? metadata.graphic.value : "http://www.unrecorded.mu/wp-content/uploads/2014/02/St.-Vincent-St.-Vincent1.jpg"
return props // Return the props to the component
}
// This is where we would implement a way to communicate back to redux if there was some action the user can take to change our state. More on that later
const mapDispatchToProps = (dispatch) => {
return {}
}
// Connect this container with the component which will use it and export it
export const MediaMetadata = connect(
mapStateToProps,
mapDispatchToProps
)(MediaPlayerBody)
export default MediaMetadataThe last thing we need to do is make sure that in our react application we are now using our container instead of the original react component which is not connected, and that the react component is using the properly named props which were passed by the container in render. In this example, this was done in MediaPlayer.js
// MediaPlayer.js
...
import { MediaMetadata } from './containers/Metadata';
export default class MediaPlayer extends React.Component {
constructor() {
super();
}
render() {
return ( // We created the MediaMetadata container in this tutorial
<div>
<AppHeader backLink="/" menuName="Apps"/>
<MediaMetadata />
<ProgressBar />
<Buttons />
</div>
)
}
}The component we actually connected was the MediaPlayerBody, let's take a look to see how the props we created off the state in the container are used
import React from 'react';
import AlbumArt from './AlbumArt';
import MediaTrackInfo from './containers/MediaTrackInfo_c'
export default class MediaPlayerBody extends React.Component {
constructor(props) {
super(props);
}
render() {
return (
// mainFields and graphic - Perfect. Those exist because this component is connected to our redux state by the container.
// Any time SDL changes the state that is tied to this component, this component will re-render and update.
<div className="media-player-body">
<AlbumArt image={this.props.graphic} />
<div className="media-track">
<p className="t-small t-medium th-f-color">{this.props.mainField3}</p>
<p className="t-large t-light th-f-color">{this.props.mainField1}</p>
<p className="t-large t-light th-f-color-secondary">{this.props.mainField2}</p>
<MediaTrackInfo />
</div>
</div>
)
}
}There are many situations where a user's action in the React Application needs to trigger a message to be sent to SDL. For example, after an application uses the AddCommand RPC to add items to the App's in-HMI menu, and the user selects one of those items, we need to be able to tell SDL about that selection by sending the notification called UI.OnCommand to SDL Core so it can be relayed to the connected application. We do this by implementing the mapDispatchToProps function in our container. For the menu, this function does two things - changes state by called dispatch (in the same way we changed our state before in our sub-controller) and sending a message to a sub controller to notify SDL Core about the event.
const mapDispatchToProps = (dispatch) => {
return {
onSelection: (appID, cmdID, menuID) => { // Our function is called onSelection, so the component can use this.props.onSelection()
if (menuID) {
dispatch(activateSubMenu(appID, menuID)) // We can used the passed in dispatch to change state (don't forget to define and import the action activateSubMenu)
}
else if (cmdID) {
uiController.onSystemContext("MAIN", appID) // We can call functions on uiController (again, don't forget to import) which send messages to SDL
uiController.onCommand(cmdID, appID)
}
}
}
}From here, the only thing left to do is implement the functions called on the sub controller. When the sub controllers imported by the main Controller, the main controller adds a function called addListener. The sub-controller can use the listener to send messages directly to SDL Core.
// UIController.js
onSystemContext(context, appID) {
this.listener.send(RpcFactory.OnSystemContextNotification(context, appID))
}
onCommand(cmdID, appID) {
this.listener.send(RpcFactory.OnCommandNotification(cmdID, appID))
}The only thing left to do now is to make sure the connected React Component is properly using the method we defined in mapDispatchToProps. In this example, it's the HScrollMenu which passes the onSelection prop to an HScrollMenuItem which calls onSelection as we've defined
// HScrollMenuItem.js
onClick={() => this.props.onSelection(this.props.appID, this.props.cmdID, this.props.menuID)}>The last common activity required to implement an SDL HMI completely is the ability to change views based on messages received by SDL. Views in the React Application are defined by Routes. When a user selects an item that changes the view, a route is taken such as /inapplist. We can force a route to be taken using React Routers withRouter. Right now, since the AppHeader component is rendered in every single view, it is responsible for forcing a change to routing history (thereby changing the view) when it renders. So the flow is
- Message comes into SDL
- Dispatch to store
- Implement Action and change app state in Reducer
- AppHeader is rendered
- AppHeader checks state to see if a change needs to be forced
- If a change needs to be forced, AppHeader makes the change
- Everything re-renders
This forced change is done in the React lifecycle method called componentWillReceiveProps, which gives the AppHeader access to the nextProps that will be used in the components render before it's rendered and in time to make a change.
// AppHeader.js
// withRouter will give us access to router on this components props
import { withRouter } from 'react-router';
...
componentWillReceiveProps (nextProps) {
if (nextProps.isDisconnected) {
this.props.history.push("/") // The app got disconnected so we force a change back to the menu
}
}
...
export default withRouter(AppHeader) // Hook this component up with router.This project was bootstrapped with Create React App.
In the project directory, you can run:
Runs the app in the development mode.
Open http://localhost:3000 to view it in the browser.
The page will reload if you make edits.
You will also see any lint errors in the console.
Launches the test runner in the interactive watch mode.
See the section about running tests for more information.
Builds the app for production to the build folder.
It correctly bundles React in production mode and optimizes the build for the best performance.
The build is minified and the filenames include the hashes.
Your app is ready to be deployed!
See the section about deployment for more information.
Note: this is a one-way operation. Once you eject, you can’t go back!
If you aren’t satisfied with the build tool and configuration choices, you can eject at any time. This command will remove the single build dependency from your project.
Instead, it will copy all the configuration files and the transitive dependencies (Webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except eject will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.
You don’t have to ever use eject. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.