[MirrorLink Hackathon] Intro to the MirrorLink API, requirements & tools by Ed Pichon

© 2014 Car Connectivity Consortium. All Rights Reserved.
MirrorLink API Overview
Introduction to the MirrorLink Common API, Requirements & Tools
Ed Pichon, App CB
2015-05-18 ver 1.1

© 2014 Car Connectivity Consortium. All Rights Reserved. 2015/05/18
Info Session Agenda
• What is MirrorLink?
• MirrorLink Common API
• Application Requirements
• App Certificates
• Support Tools

Basic MirrorLink®
Concept
Once connected,
no need to touch or
look at your phone

What is MirrorLink?
High Level Overview for Application Developers
• MirrorLink is a Protocol for Using Automotive
Head Units (Clients) as Remote Terminals for
Phones (Servers)
• Uses/extends a number of open standards
• Physical layer agnostic
• Services Provided
• Framebuffer replication
• Control events
• Bi-directional audio
• Bi-directional data services
• MirrorLink Services Provided Transparently to the
Application
• Apps don’t have to implement ML protocol
• Thin API provides access to info about ML session
and some basic commands
• Applications Execute On the Phone, But Are
Viewed and Used on the Head UnitMirrorLink Client
(Head Unit)
MirrorLink Server
(Phone)
MirrorLink Common API
Application

MirrorLink Common API
Quick Survey of Exposed Capabilities

MirrorLink Common API Modules
Module Obligation Summary
Common API Info Mandatory Module availability and version info.
Device Info Mandatory MirrorLink version, head unit info*
Certification Information Mandatory Certificate status introspection
Connection Information Mandatory Connection status*
Display Information Mandatory Head unit screen size*, orientation status*
Event Information Mandatory Head unit buttons*
Client Virtual Keyboard Optional VKB provided by head unit interface
Key Event Listing Optional VKB provided by head unit interface
Context Information Mandatory Audio/video metadata, blocking*
Device Status Information Mandatory Drive/Park mode*, microphone*
Data Services Optional Data object model interface*
Notifications Optional Head unit notification interface*
* - Callback available

Application Metadata
Quick overview
• Provide Information to the ML Client
About the Application
• Audio Content Categories
• Application categories of audio streams
• Set at runtime using Common API
• Head unit uses info to mix audio feeds
• Other Metadata (Deprecated)
• Video Application Categories
- Deprecated
• Visual Content Categories
- Deprecated
• Audio Content Types
- System Services
- Don’t use!
App Category
Navigation
Visual Content Category
Vector Graphics
App Category – General UI Framework
Visual Content Category – Vector Graphics
App CB’s Advice: Set Audio
Content Category at run-time
whenever app starts playing audio.
(Set other metadata in application certificate, &
don’t modify at run-time.)

Head Unit Display Info
• Information Provided
• Size of ML screen in pixels
• Size of ML screen in millimeters
• Distance to user (if known)
• Scaling support info – padding rows/columns for
aspect ratio, etc.
• Client pixel format (565, 888, etc.)
• Can Set Orientation Support of App at RunTime
• Callback – Info Can Change While in a
MirrorLink Session
• Screen windowing
• Overlays
• Minimizing
• Orientation change request (can reject!)
Full Head Unit Screen
ML Window
(Reported Screen Size)
Full Head Unit Screen
Initial Window
Temp Window 1
Rotate?

Event Configuration Info
Element Description
Knob Support Knob and direction keys available
Device Key Support Dedicated keys available (make call, end call, back, etc.)
Multimedia Key Support Audio keys available (play, pause, rewind, etc.)
Function Key Support F1, F2, etc.
ITU Key Support Phone specific (*, #, 0, 1, 2, 3, 4…)
Touch event support Number of simultaneous touch events
Pressure Mask Pressure levels supported on touch events
Keyboard Language Language & country codes for client VKB
UI Language Language & country codes for client UI language

Event Configuration Discussion
• Different Head Units Have Different Capabilities
• Minimum Set – Rotary Knob OR Single-Touch (1 Pressure Level)
• Rotary knob – up/down/left/right, clockwise/counter-clockwise turn, push
• If you are going to be CCC certified, have to work with both
• Event Configuration Can Change at Runtime…in Theory
• I haven’t seen it yet
• Can Tailor Application UI Based on Head Unit Capabilities
• One UI for rotary know and one UI for single-touch
• One UI for multi-touch
• One UI for park and one UI for drive
• We Test Each UI Layout in Certification Testing
App CB’s Advice: Build One UI That
Works With Rotary & Single-Touch

Data Services
• Extensible Data Object Model for Exchanging Data between Head Unit
and Phone
• Bi-directional
• Not always available – some phones/head units don’t support
• Currently Two Services Defined
• GPS
• Location
• GPS and Location Mapped Directly to Location Services in Android
• Typically higher accuracy/reduced latency vs. on-phone capabilities
• Your app gets access for free!
• Additional Services Being Defined by CCC
• Let us know what you’d like to see!

Application Requirements
Quick Survey

Application Requirements
• Base Requirements “Park Mode” – Ensure Applications Can Be Used
• Application supports multiple UI schemes
- Different screen sizes
- Different controls
› Rotary knob
› Touch screens
• Application doesn’t require use of OS keys that may not be available
• Useful for alternate use cases of MirrorLink
• Drive Requirements – Ensure Applications Do Not Excessively Distract
Driver
• Does not show forbidden content
• Does not demand user’s attention
• Easy for the user to read and interact with
• Does not consume too much of the driver’s attention (driver workload)

Base Requirements
Basic Interoperability
Display Compatibility
• Support Reference Client
Display
• 800 x 480 pixels (square)
• 13.33 cm x 8.00 cm
• 90 cm from driver
• Adapt to Client Display
[Optional]
• Support Landscape Mode
• Control Positioning
• Not entirely within outer 5% of
the display
Control Compatibility
• Support Rotary Knobs
• May not have a rotary keyboard
available, so either implement
your own, or don’t require
• Support Single-Touch Events
• Cannot require multi-touch
• Voice Commands
• May use, but may not be
available
• Must notify user if not available
• Cannot Require OS Keys
• May not be present on Client
• Provide Application Metadata
Benefit – App Will Work With ML Clients

Drive Requirements
Minimizing Driver Distraction
• Guiding Principals
• Nothing that demands the driver’s attention
• Quickly comprehensible and accessible
• Restricted Content
• No video, incidental animations or flashing
• No automatic scrolling text
• Visual Accessibility
• Color contrast – brightness & color differences
• Text legibility
• Minimum height
• Font requirements
• Control Accessibility
• No two-handed operations
• Should not use the keyboard
• Control sizing and spacing
• Pace of Interaction
• Input retention and responsiveness
• Notification dismissal
Region-Based
Certification
• Region Specific
• North America (AAM)
• European Union (EU)
• APAC (JAMA)
• Global Certification
• Superset of NA, EU and
APAC guidelines
• Can Get Certified for One
or Multiple Regions
• E.g. Drive in EU & APAC, but
not NA

Drive Certification Regions
Clarification
• EU Requirements are the Minimum Set
• Applies to all regions that do not have a requirement set
• If your app isn’t targeting NA or Japan, go with EU requirement set
• NA Requirements: EU + Driver Workload
• Japan Requirements: EU + Strict(er) Driver Workload
• Global Requirements are Superset – Japan Requirements
• Working on Defining New Regional Requirements
All Regions (EU Requirements)
North America
Japan

• Primary Text Must Be At Least (≥) 4.2 mm Tall
• Secondary, supplemental text must be at least (≥) 3.2 mm tall
• Must Comply With Legibility Requirements
• Use a pre-approved font (most of the Android fonts)
• Comply with various spacing/stroke ratio requirements
• Don’t use cursive handwriting fonts or ones with lots of
decorative elements
• Map/Icon Content is Exempt
Drive Requirements
Text Accessibility Requirements Detail
Make Your Text Big, Use Default Fonts

• Foreground Elements Must Have a W3C Contrast Ratio of At Least 7:1
to their Background
• Allows for legibility in high-glare conditions
• Defined Pre-Approved Color Combinations
• Can use those color combinations, or ones where RGB values are “wider”
• Can add color combination to pre-approved list – CCC will test
- Derived from ISO specs, and we check on multiple head units/lighting
conditions
• This Applies to Text, Icons & Controls
• If the user needs to be able to see it, it needs to be clearly visible
• Map content is exempt
• Disabled controls have lower threshold
Drive Requirements
Color Contrast Requirements Detail
Choose Colors Carefully!

Drive Requirements
Control Accessibility Requirements Detail
• Visual Representation of Controls Have to Be At Least 200 mm2
, With a
Minimum Dimension of 10 mm
• Must Fill up 50% of the Containing Box
• Must be a Border Between Controls

Accessibility & Screen Size
Dealing with Multiple Client Screen Sizes
• Client Screens Can Have Multiple Sizes
• Reference Client Display used for Driver Testing
• Resolution: 800 x 480 (assuming square pixels)
• Physical sizes: 13.33 cm x 8.00 cm (width x height)
• Distance to the eye of the driver: 90.00 cm
• Scaling Up & Down Takes Place Automatically
• If ML Client is Larger Than Reference Client Display:
• App doesn’t have to do anything – scaling makes text/controls larger
• May tailor UI to take advantage of larger size, but don’t have to
• Not Required to Comply with Size Requirements on ML Clients Smaller
than Reference Client Display
App CB’s Advice: Build for the Reference
Client Display, & Don’t Worry About Scaling

Driver Workload Verification
Human Subject Testing
• Short Version – No More Distracting Than Tuning a Radio
• Required Test For Global, NA or Japan Certification
• Japan is the more stringent requirement
• Basic Requirement
• 10 subjects, half male, half female, range of ages
• Occlusion goggles or blanking display – 1.5 seconds on, 1 second off
• Average time to perform longest task ≤ 7.5 seconds total open time
- 5 “on” cycles
- NA – 20 subjects, ≤15 seconds total open time for 85% of
participants
• How We Do It
• CCC approved Subject Matter Expert (SME) assesses application
• Identifies tasks that need to be evaluated
• Test lab screens tasks to find ones that take longest
• Test 3 longest tasks (and key tasks identified by SME)
Keep Lists and Tasks Short & Simple

ACMS & App Certificates
App Certificate Management System

Two Kinds of Certificates
• Self-Signed Application Certificate
• Included with the APK
• Application metadata
• Indicate to phone if it should check for a “real” certificate from the
ACMS
• Optional: Indicate to the phone if it is a developer application
• CCC Application Certificate
• Distributed by the CCC’s App Certificate Management System (ACMS)
• Indicates to the phone that is a certified app
• May be CCC certified – required to be presented to the user
- Tested by the CCC as being compliant with our requirements
• May be whitelisted by an OEM – required to be presented to user if
head units is from that OEM
• …or both!

Car Connectivity Consortium
App Certificate
Management System
Application Certificate Management System
ACMS for App Developers
24
Certificate
Distribution
Management
Portal
App & Dev
Certificates
MirrorLink®
Server Devices
Phones & other mobile devices
Apps
Apps
Device Makers
Developers
Test Labs
MirrorLink®
Client Devices
Head units
App Stores Apps do not contain
Application Certificates.
Application Certificates
distributed to server
devices over the Internet.
App Certificate tells Servers
& Clients when the app is
safe to use, and where.
ACMS Integration Requires No
Changes to Application
Certification Body

Application Certificate Information
Application Metadata
<appIdentifier>ACMSDemo1234abcd</appIdentifier>
<appListEntry>
<name>ACMS Demo 1</name>
<providerName>E-Qualus</providerName>
<providerURL>www.e-qualus.com</providerURL>
<description>A demo app.</description>
<iconList>
<icon>
<mimetype>image/png</mimetype>
<width>72</width>
<height>72</height>
<depth>24</depth>
<url>/resources/icon.png</url>
</icon>
</iconList>
<appInfo>
<appCategory>0x00080000</appCategory>
</appInfo>

Application Certificate Information
Certification Status
<appCertInfoEntry>
<appUUID>uuid:abcd1234-abcd-1234-5678-abcdef123456</appUUID>
<entity>
<name>CCC</name>
<restricted>EU</restricted>
<nonRestricted>EU, USA,AUS,KOR,CHN,APAC,WORLD</nonRestricted>
</entity>
<entity>
<name>OEM-A</name>
<restricted>USA,EU</restricted>
<nonRestricted>EU,USA,AUS,KOR,CHN,APAC,WORLD</nonRestricted>
</entity>
<entity>
<name>OEM-B</name>
<restricted>USA,EU</restricted>
<nonRestricted>EU,USA,AUS,KOR,CHN,APAC,WORLD</nonRestricted>
</entity>
</appCertInfoEntry>

Allowed Certificate Entity Names
What is Allowed in the <entity><name> Block
• CCC (CCC Application Certificates ONLY)
• Certified by the CCC
• All head units will show the app as a certified app
• All head units will pay attention to the restricted (drive) and non-restricted
(park) modes
• OEM Name (CCC Application Certificates ONLY)
• Head units from that OEM will treat that app as certified
• Whitelisting by individual OEMs
• Added to certificates at request/approval of OEM
• ACMS (Self-Signed Certificates ONLY)
• Indicates that the phone should check with the ACMS for a certificate
• Developer (Self-Signed Certificates ONLY)
• Indicates that this is a developer certificate
• Reported as “CCC” to head unit if developer certificate validation
successful

Developer Certificates
See the Developer Application
Certificate Tutorial for more
information.
https://causeway.carconnectivity.
org/wg/DevWG/document/3130

Developer Support Tools
Aids to Developing ML Applications

Protocol Implementation
Conformance Statement
• PICS is a Spreadsheet Filled Out by the App Developer
• Identification information about the app
• Requirements checklist
• Description of application
- What are the screens?
- How does application adjust to head-unit capabilities?
- What fonts to do you use?
• Used by the CCC and the ATL to Determine Which Tests to Run
• If you don’t have any maps in your app, we don’t check that your app complies
with the navigation requirements
• If EU-certified only, no need to run driver workload tests
• Used by the ATL to Determine How to Run Tests
• What screens to examine for compliance and how to get to them
• What client capabilities needed to examine all variations?
• Critical to Certification Program – We Rely On You to Be Honest
• Test labs will check that your app matches the PICS

Application Certificate XML Extension
• XML Data for Application
Certificates Builder
• Presentation information to show user
on head unit: Icon, Name, etc.
• Content of application: video and
audio content categories (navigation,
music, etc.)
• Certification status information: who
has certified for what regions
- Multiple certifying entities: CCC,
Car Maker, etc.
- Multiple possible regions
- Car-maker specific information
• Guides on Structure and Data
Fields
31

Application Certificate Generation
• Certificate Builder
• Create Self-Signed
Certificates to Include in
Application APK
• Automatically generate
Android Application IDs
• Build Regular Self-
Signed Certificates and
Developer Certificates
• Linux and Windows
Versions
32

Android Common API Simulator &
Controller
• Common API Simulator APK
• Can be installed on any Android device (API level >
14)
• Provides a “fake” MirrorLink Common API
to other applications on device
• Common API Simulator Controller
• Runs on separate PC (Ubuntu & Windows)
• Controls behavior of MirrorLink API
• Configure simulator MirrorLink session
capabilities
• Configure responses API calls
• Trigger events
- Change Client screen sizes
- Button pushes
- Simulate data service objects
• Only Works on Phones That Don’t Have MirrorLink
• Doesn’t make a phone a ML phone!
33

ML Client Simulator
• Built by Head of Technical Working Group
• Full Featured Simulator of MirrorLink 1.1
Client on an Ubuntu PC
• DAP, Simulated Data Source, Receive
Audio
• Variable session capabilities
- Screen size
- Offered services and controls
• Certification pending
• Used in Certification Testing of Apps
• Allows for internal testing of driver
distraction at the developer workstation
• Provided by Microsoft (No Cost!)
• Must agree to license terms with Microsoft
• jorg.brakensiek@microsoft.com
34

Rotary Shift Knob
• Some MirrorLink Clients Use
a Rotary Shift Knob
• Custom hardware device
• No common equivalent in PC
space
• Applications Are Required to
Support the Rotary Shift
Knob
• Instructions for Assembling
Your Own
• CAN-USB interface dongle
• C-Class Control Knob from
Daimler
• 12 V DC power supply
• 60Ω termination resistor
35

Common API Test Application
• Used for Certification of Server
Implementations of Common API
• User interfaces for each element of
Common API
• Testing support tools
• Great Way for Developers to Learn
About Common API
• What information is exposed
• What commands are available
• Source Code Provided to
Developers
36

ML 1.1 Devices
• MirrorLink 1.1 is First Version of MirrorLink that Supports 3rd
Party
Apps
• 1.0 just allowed first-party built-in car-mode apps
• MirrorLink 1.1 Phones (Servers) Now On the Market
• HTC One M8
• Samsung Galaxy S4 Mini, Note 4, And Others
• Sony Xperia Z3
• Others pending
- In testing
- Certified but not publicly announced
• ML 1.1 Head Units (Clients)
• New VW, Honda, Toyota, Peugeot, Skoda
• Pioneer AVH-X5700BHS (Aftermarket)
• Others pending
• Check the Certified Products Listing on MirrorLink.com

Why Make an App a MirrorLink App?
Advantages of implementing MirrorLink in Your Apps
• Open Standard
• No one company controls, no one company can change the rules
• Not tied to a single OS or platform
• Broad Install Base
• Most car manufacturers are adding MirrorLink to their head units
• Clear, Open Requirements
• You know what the rules are
• Maximum Flexibility
• As long as you comply with the requirements, you can do what you like
• Minimal Technical Burden
• No SDK, just a thin API
• You Can Focus on the User Experience

Thanks
• Feel Free to Email Me if You Have
Questions
• ed.pichon@carconnectivity.org
• Register as a Developer at Mirrorlink.com!
• Weekly Test Status Review Call
• 9:30am Central Time, Thursdays
• Webex posted to Developer Portal
• Open to all developers
• If you have a problem with a test case, you can
ask here.
• Can route questions through CB (me) to keep
identify anonymous

[MirrorLink Hackathon] Intro to the MirrorLink API, requirements & tools by Ed Pichon

More Related Content

What's hot (20)

Viewers also liked (15)

Similar to [MirrorLink Hackathon] Intro to the MirrorLink API, requirements & tools by Ed Pichon (20)

More from BeMyApp (20)

Recently uploaded (20)

[MirrorLink Hackathon] Intro to the MirrorLink API, requirements & tools by Ed Pichon