CalAmp FOB10 Bluetooth 4.0 Low Energy Keyfob User Manual

CalAmp Bluetooth 4.0 Low Energy Keyfob

User Manual

BLE KEYFOB™
Hardware and
Installation Guide
Version 1.0.0
SEPTEMBER 1, 2015
License Agreement
FOR SOFTWARE, APPLICATION PROGRAMING INTERFACES (APIS) & DOCUMENTATION
IMPORTANT: DO NOT INSTALL OR USE THE SOFTWARE OR DOCUMENTATION UNTIL YOU HAVE
READ AND AGREED TO THIS LICENSE AGREEMENT.
This is a legal agreement between you, the Customer, and CalAmp DataCom Incorporated
(“CalAmp”). By installing and/or using the software or documentation, you are consenting to the
terms of this License. If you do not agree to the terms of this non-exclusive License Agreement, DO
NOT INSTALL OR USE THE SOFTWARE, APIs OR DOCUMENTATION. For a full refund, return the
unused media package and all accompanying materials within seven (7) days to CalAmp. Where
there is no packaging or media, use of the software and/or documentation constitutes acceptance.
DEFINITIONS: As used in this License Agreement, “Software” means CalAmp’s LM Direct™, LMU
Manager™, LapTop Locator™, LMU Application/Programmable Event Generator™, CDMA LMU
Provisioning Tool, GPRS LMU Provisioning Tool, iDEN™ Provisioning Tool, LMU Status, Clone Config,
Hex Dump, LM Exchange™ Traffic Monitor, Freewave Base Station Config, Remote Serial Port, App
Watcher Service and/or other software products licensed by CalAmp for use in computer
applications development or integration including the computer programs, libraries and related
materials either contained on the media provided to you by or from CalAmp, or which you have
received or downloaded electronically. “Application” means a compiled or executable software
program created by Developer that uses some or all of the functionality of the Software. “Software
Copies” means the actual copies of all or any portion of the Software including backups, updates,
merged or partial copies permitted hereunder or subsequently licensed to you. “Documentation”
means the non-Software information contained on the media provided with this package or
downloaded and which is used with and describes the operation and use of the Software.
“Documentation Copies” means the actual copies of all or any portion of the Documentation
including backups, updates, merged or partial copies permitted hereunder or subsequently provided
to you. “Related Materials” means all other materials and whatever is provided by or from CalAmp,
and the non-Software and non-Documentation contained on the media supplied, downloaded, or
otherwise supplied by or from CalAmp for use with the Software and Documentation. “Server”
means a single, networked computer that is accessible to other client machines on the network.
“User” means (i) a single person using an Application for his/her internal, use or (ii) a single terminal
or a single workstation of a computer used only by a person (and not accessed otherwise) for
accessing an Application. “Use License” means limited rights granted by CalAmp for deployment of a
single Application to a User. “Developer” means a single programmer developing an Application.
“Developer License” means the grant of certain limited rights to use and maintain the Software,
Software Copies, Documentation, Documentation Copies and Related Materials in development of
Applications.
BACKGROUND: A Developer License is required for each Developer who uses the Software in building
Application(s). A Use License is required and must be purchased by Customer for each User to which
Customer provides access to an Application (unless a Server or Site license for unlimited or a
specified number of users has been purchased). Each Use License is specific to one client-side
Application only and may not be used for any other client-side Application. Each Server license is
limited to Server-based Applications deployed on that Server for which the license has been
purchased as specified in a CalAmp License Certificate. The Software is licensed on a per Developer,
and on a per User, per Application basis. In order to preserve and protect its rights under applicable
law, CalAmp is not selling you ownership rights to Software or Documentation (owned by or licensed
to CalAmp). CalAmp specifically retains title to all CalAmp Software, Documentation and Related
Materials and CalAmp licensors retain title to items owned by them.
DURATION: This License Agreement is effective from the day you install or start using the Software, or
receive or download it electronically, and continues until terminated. If you fail to comply with any
provision of the License, termination is automatic, without notice from CalAmp and without the
necessity for recourse to any judicial authority. Upon termination, you must destroy the Related
Materials, the Software, Documentation and all Software and Documentation copies. CalAmp can
also enforce its other legal and equitable rights.
DEVELOPER LICENSE ONLY—USES PERMITTED: Software and Documentation may be used for the sole
purpose of developing Applications and only by a licensed Developer. Software and Documentation
may be installed onto a hard disk drive or a Server, access to which is restricted to Developers for
which a Developer License has been purchased and may also be stored or installed on a storage
device such as a network server, used only to install or access the Software or Documentation on
your other computers over an internal network; however, you must have acquired a license for each
separate computer on which the Software or Documentation is installed or accessed from the
storage device. A Developer License may not be shared or used concurrently on different computers.
One backup copy may be made for each legally obtained media copy or electronic copy you have
received, provided that all CalAmp and third party licensor information — including copyright
notices — are maintained and possession of the copy is retained in a secure location. In addition,
you agree to use reasonable efforts to protect the Software and Documentation from unauthorized
use, reproduction, distribution or publication. All rights not specifically granted in this License are
reserved by CalAmp.
Customer agrees to include the notice “Copyright © 1999 – 20015 CalAmp DataCom Inc., All Rights
Reserved” in Applications developed with the Software. Customer agrees to include the following
CalAmp Copyright and Government Restricted Use notice in all documentation and in any
Application on-line help or readme file.
“Portions of this computer program are owned by CalAmp DataCom Inc., Copyright © l999 – 2015,
CalAmp DataCom Inc., All Rights Reserved. Use, duplication or disclosure by the Government is
subject to restrictions as set forth in subparagraph ©(1)(ii) of the Rights in Technical Data and
Computer Software clause at DFARS 252.227-7013 or subparagraphs ©(l) and (2) of the Commercial
Computer Software-Restricted Rights at 48 CFR 52.227-19, as applicable. Manufacturer is CalAmp
DataCom Inc., 1401 North Rice Ave. Oxnard, CA 93030. Rights are reserved under copyright laws of
the United States with respect to unpublished portions of the Software.”
DEVELOPER(S) LICENSE—USES NOT PERMITTED: UNLESS OTHERWISE AGREED TO IN WRITING WITH CALAMP, YOU
MAY NOT (1) Make derivative works including but not limited to translations, adaptations,
arrangements or any other alteration (each of which would become the property of CalAmp or its
licensors, as applicable) or make copies of the Software or Documentation except as permitted
above; (2) Make copies of the Related Materials; (3) Use any CalAmp product to translate the
product of another licensor unless you have the legal right to do so; (4) Allow a greater number of
Developers to access the Software at any one time than the total number of Developer licenses for
which you have paid; (5) Rent, lease, sublicense or lend the Software, Software Copies,
Documentation, Documentation Copies, Related Materials or your rights under this License or allow
access to the Software for unlicensed users; (6) Alter, decompile (except to the limited extent that
decompilation by the licensed Developer only is necessary as the only available way to achieve
interoperability with other programs and, in that situation, any resulting information cannot be used
in developing, producing or marketing any software substantially similar in expression to the
Software), disassemble or reverse engineer the Software; (7) Make any attempt to unlock or bypass
any initialization system or encryption techniques utilized by the Software or Documentation; (8)
Alter, remove or obscure any proprietary legend, copyright or trademark notice contained in or on
Software, Documentation or Related Materials; or (9) use the Software to create an Application
intended solely to duplicate functionality of an existing CalAmp end user software product.
USE LICENSES: For each Server or Site License purchased, CalAmp grants the Customer the right to
distribute Applications on a single Server or at a single Site, as the case may be, accessible to the
number of individual users (not concurrent users) for which the Server or Site License has been
purchased as evidenced by a CalAmp License Certificate. For each Use License purchased, as
evidenced by a CalAmp License Certificate, CalAmp grants the Customer the right to distribute a
single Application to a single User. In no circumstance may Customer distribute an Application under
a site license or concurrent use license unless a comparable license has been purchased for the
Software as evidenced by a CalAmp License Certificate. Customer agrees that distribution of an
Application to a User will in all cases be accompanied by a license agreement containing at a
minimum terms and conditions substantially similar to and at least as restrictive as the following:
The User may not (1) Make derivative works including but not limited to translations, adaptations,
arrangements or any other alteration of the Application or make copies of the Application, except
one backup copy may be made for each legally obtained copy of the Application, provided that all
CalAmp and third party licensor information — including copyright notices — are maintained and
possession of the copy is retained in a secure location; (2) Allow access to the Application for
unlicensed users; (3) Rent, lease, sublicense or lend the Application or its rights under the license; (4)
Alter, decompile, disassemble or reverse engineer the Application; (5) Make any attempt to unlock
or bypass any initialization system or encryption technique utilized by the Application; or (6) Alter,
remove or obscure any proprietary legend, copyright or trademark notice contained in or on the
Application.
The User agrees to use reasonable efforts to protect the Application from unauthorized use,
reproduction, distribution or publication.
AUDIT: Customer shall keep records of all transactions involving Software for five (5) years after the
transaction. CalAmp shall have the right upon written notice to audit Customer’s records to verify
compliance with this License including the number of Use Licenses granted by Customer. Audit may
take place at Customer’s place or business during normal working hours. In the event that there is a
discrepancy in excess of five percent (5%) between the number of Use Licenses granted and the
number paid for, Customer shall pay all costs related to performing the audit in addition to remitting
payment for those licenses granted in excess of those paid for as evidenced by a CalAmp License
Certificate.
GENERAL: This Agreement represents our entire understanding and agreement regarding the
Software, Software Copies, Documentation, Documentation Copies and Related Materials and
supersedes any prior purchase order, communication, advertising or representation and may only be
modified in a written amendment signed by an authorized CalAmp representative or by a specific
prior or subsequent written agreement between the parties. If any provision of this Agreement shall
be unlawful, void or for any reason unenforceable, that provision shall be deemed severable from,
and shall in no way affect the validity or enforceability of, the remaining provisions.
Limited Warranty
COVERING THE PHYSICAL MEDIA AND PRINTED MATERIALS: CalAmp warrants to you, the original licensee,
that the media on which the Software is recorded are free from defects in materials and
workmanship under normal use and service FOR A PERIOD OF NINETY (90) DAYS FROM THE DATE OF
DEVELOPER LICENSE PURCHASE. CalAmp’s entire liability and your exclusive remedy as to defective
media, Documentation or Related Material(s) shall be replacement of the media, Documentation or
Related Material(s) by CalAmp. Each defective item, along with proof of license purchase and date,
must be sent in a traceable manner to: CalAmp DataCom Inc., 1401 North Rice Ave. Oxnard, CA
93030.
DISCLAIMER REGARDING THE SOFTWARE, DOCUMENTATIONS AND RELATED MATERIALS: THE SOFTWARE,
DOCUMENTATION AND RELATED MATERIALS ARE PROVIDED “AS IS.” EXCEPT AS MAY OTHERWISE BE
EXPRESSLY SET FORTH HEREIN, CALAMP MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS
OR IMPLIED, WITH RESPECT TO THE SOFTWARE, DOCUMENTATION OR RELATED MATERIALS
INCLUDING BY WAY OF EXAMPLE, AND NOT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. BY WAY OF FURTHER EXAMPLE AND
NOT LIMITATION, CALAMP MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED,
WITH RESPECT TO THE ACCURACY, RELIABILITY OR COMPLETENESS OF THE DOCUMENTATION OR
THE RELATED MATERIALS. THE ENTIRE RISK AS TO THE USE OF THE SOFTWARE, DOCUMENTATION
AND RELATED MATERIALS IS ASSUMED BY YOU. IN NO EVENT SHALL CALAMP BE LIABLE TO YOU OR
ANY OTHER PERSON, REGARDLESS OF THE CAUSE, FOR THE EFFECTIVENESS OR ACCURACY OF THE
SOFTWARE, DOCUMENTATION OR RELATED MATERIALS OR FOR ANY SPECIAL, INDIRECT,
INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING FROM OR OCCASIONED BY YOUR USE OF THE
SOFTWARE, DOCUMENTATION OR RELATED MATERIALS, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES. IN THE EVENT THE FOREGOING IS FOUND BY A COURT OF COMPETENT
JURISDICTION TO BE INEFFECTIVE, YOU HEREBY AGREE THAT CALAMP’S MAXIMUM LIABILITY FOR
ANY CLAIM ARISING IN CONNECTION WITH THE SOFTWARE, DOCUMENTATION AND/OR RELATED
MATERIALS (WHETHER IN CONTRACT, TORT, INCLUDING NEGLIGENCE, PRODUCT LIABILITY OR
OTHERWISE) SHALL NOT EXCEED THE LICENSE FEES PAID BY YOU WITH RESPECT TO THE SOFTWARE,
DOCUMENTATION AND/OR RELATED MATERIALS AT ISSUE. SOME STATES DO NOT ALLOW THE
LIMITATION OR EXCLUSION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THE FOREGOING
PROVISION, WITH RESPECT TO EXCLUDING OR LIMITING SUCH DAMAGES, MAY NOT APPLY TO YOU.
ACKNOWLEDGEMENT: You acknowledge that you have read this LIMITED WARRANTY, understand it
and agree to be bound by its terms and conditions. You also agree that: (1) No oral or written
information or advice given by CalAmp, its dealers, distributors, agents or employees shall in any
way increase the scope of this Limited Warranty and you may not rely on any such information or
advice; (2) Unless a written governing agreement signed by you and CalAmp exists, this License
Agreement is the complete and exclusive statement of agreement between CalAmp and you
regarding the licensing of the Software, Documentation and Related Materials and supersedes all
proposals, oral or written, and any other communications you may have had prior to purchasing
your license; (3) Except for the price and delivery terms agreed upon by both parties, the terms and
conditions of this License Agreement shall supersede those set forth in any purchase order where
the purchase order conflicts or is inconsistent with or adds to the terms and conditions of this
License and those superseded purchase order terms and conditions shall be null and void; (4) You
agree to assure that copies of this License Agreement are distributed, read and agreed to by each
Developer using the Software and/or Documentation.
GOVERNING LAW: This Agreement shall be governed by the laws of the State of California, United
States, excluding its conflicts of law principles and excluding the United Nations Convention on
Contracts for the International Sale of Goods. You agree to exclusive jurisdiction of California State
federal and state courts, Ventura County, for resolution of any dispute related to this Agreement.
U.S. GOVERNMENT PROTECTED RIGHTS: The Software Documentation and Related Materials are
provided with RESTRICTED RIGHTS. Use, duplication or disclosure by the Government is subject to
restrictions as set forth in subparagraph ©(1)(ii) of the Rights in Technical Data and Computer
Software clause at DFARS 252.227-7013 or subparagraphs ©(1) and (2) of the Commercial Computer
Software-Restricted Rights at 48 CFR 52.227-19, as applicable. Manufacturer is CalAmp DataCom
Inc., 1401 North Rice Ave. Oxnard, CA 93030. Rights are reserved under copyright laws of the United
States with respect to unpublished portions of the Software.
Regulatory Information
FCC Rules
Compliance Statement (Part 15.19)
The enclosed hardware device complies with the Part 15 of the FCC Rules. Operation is subject to the following
two conditions: (1) This device may not cause harmful interference, and (2) This device must accept any
interference received including interference that may cause undesired operation.
FCC ID: APV-FOB10
IC ID: 5843C-FOB10
M/N: FOB10-BL
Manufacture: CalAmp Corp.
Warning (Part 15.21)
Changes or modifications not expressly approved by CalAmp could void the user’s authority to operate the
equipment. Manufacturer is not responsible for any radio or TV interference caused by unauthorized
modifications to this equipment.
Compliance Statement (Part15.105(b))
This equipment has been tested and found to comply with the limits for a Class B digital device, pursuant to
Part 15 of the FCC Rules. These limits are designed to provide reasonable protection against harmful
interference in a residential installation. This equipment generates, uses and can radiate radio frequency
energy and, if not installed and used in accordance with the instructions, may cause harmful interference to
radio communications. However, there is no guarantee that interference will not occur in a particular
installation. If this equipment does cause harmful interference to radio or television reception, which can be
determined by turning the equipment off and on, the user is encouraged to try to correct the interference by
one or more of the following measures:
• Reorient or relocate the receiving antenna
• Increase the separation between the equipment and receiver
• Connect the equipment into an outlet on a circuit different from that to which the receiver is
connected.
• Consult the dealer or an experienced radio/TV technician for help.
Industry Canada (IC) regulatory information
This device complies with Industry Canada licence-exempt RSS standard(s). Operation is subject to the
following two conditions: (1) this device may not cause interference, and (2) this device must accept any
interference, including interference that may cause undesired operation of the device.
Le présent appareil est conforme aux CNR d’Industrie Canada applicables aux appareils radio exempts de
licence. L’exploitation est autorisée aux deux conditions suivantes : (1) l’appareil ne doit pas produire de
brouillage, et (2) l’utilisateur de l’appareil doit accepter tout brouillage radioélectrique subi, même si le
brouillage est susceptible d’en compromettre le fonctionnement
CAN ICES-3 (B)/NMB-3(B)
Driver ID Keyfob system design
Table of contents
Driver ID Keyfob system design .......................................................................................................... 1
Key Fob button pushes ..................................................................................................................... 10
Button state machine ignoring debouncing ................................................................................. 10
button state coded as 2 bits ......................................................................................................... 10
Configuration for each button ...................................................................................................... 11
Event generation mask for each button coded as 1 byte ............................................................. 11
Keyfob configuration......................................................................................................................... 11
OTP (factory set configuration) ..................................................................................................... 12
Keyfob button timing diagrams for common scenarios. .................................................................. 12
Short press showing de-bouncing other buttons not pressed. .................................................... 12
LMU-FOB comms .............................................................................................................................. 13
Advertisement packet contents .................................................................................................... 13
Calamp Fob data contents ............................................................................................................ 13
Version letter encoding ................................................................................................................. 14
txpw contents ............................................................................................................................... 14
Scan response packet contents .................................................................................................... 15
Overview of Bluetooth Automatic Driver ID process ........................................................................ 15
State Machine for driver ID discovery .......................................................................................... 15
State Machine for Finding Fobs using Beeps and Buttons ............................................................ 15
Description .................................................................................................................................... 15
Sequence diagram of discovery of driver id when only one fob in range .................................... 18
Sequence Diagram of discovery of driver ID using buzzer and button ......................................... 19
Sequence diagram of connecting to a single fob to sound buzzer during driver id discovery ..... 20
Bluetooth LE services .................................................................................................................... 21
New PEG triggers .......................................................................................................................... 21
New Trigger modifiers................................................................................................................... 21
New PEG actions ........................................................................................................................... 22
Params .......................................................................................................................................... 22
Driver’s FOB Out-of-Range ................................................................................................................ 23
Over the Air Update .......................................................................................................................... 23
Format of Fob OTA ID report ............................................................................................................ 24
Work Breakdown .............................................................................................................................. 27
Build Process ................................................................................................................................. 27
Keyfob ........................................................................................................................................... 27
BTCS .............................................................................................................................................. 27
LMU ............................................................................................................................................... 27
Key Fob button pushes
Button state machine ignoring debouncing
Warning: Any key press event with time interval shorter than 1s is not going to be reliably received
by LMU FOB module when LMU BT driver is operating in Scan advert mode.
The state diagram below will only work if the KeyFob is connected to BTDB.
button state coded as 2 bits
Not pressed
00
Pre-short press
01
Short Press
10
Long Press
11
The three buttons are bit coded into a single button state byte 0 0 b3 b3 b2 b2 b1 b1
Not
Pressed
Pre-short
press
Short Press Long Press
timeout MinSP
Tx ShortPress
timeout repeat SP
Tx Shortpress
timeout LP
Tx longpress
timeout repeat LP
Tx Longpress
Button push
Tx Not pressed
Button release
Tx Not pressed
Configuration for each button
configuration units / bit size (bytes) default
Event Generation mask (see below) 1 00111100
Generate events on
releasing button from
short press & when long
pressed & keep
generating long press
events until button is
released.
Event generation mask for each button coded as 1 byte
description mask (top 2 bits are reserved)
generate message on min short press timeout 00xxxxx1
generate message on short press repeat timeout
00xxxx1x
generate message on short press release
00xxx1xx
generate message on long press timeout
00xx1xxx
generate message on long press repeat timeout 00x1xxxx
generate message on long press release
001xxxxx
Keyfob configuration
Stored on individual Keyfobs.
units / bit size (bytes) default
Short Press minimum 100ms 1 2
Short Press Repeat 100ms 1 2
Long Press time 100ms 1 15
Long Press Repeat 100ms 1 5
beacon interval
1ms
1
8750
beacon duration after keypress
1s
1
0 (always and forever)
CID n/a 2 0xFFFF
(0xFFFF is special case and is
always processed) otherwise
this CID must match the CID
in the LMU
Tx power
db
1
0
Low Battery LED blink % % 1 20
Button push LED blink
n/a
1
0x07 all 3 buttons cause blink
when pressed (0x0f if 4
buttons)
Config button 1 (see above)
n/a
1
0x3c
Config button 2 (see above) n/a 1 0x3c
Config button 3 (see above) n/a 1 0x3c
reserved (for 4
th
button) n/a 1 0x00
OTP (factory set configuration)
Description size (bytes) default
Cal Id 2 0xca1a (** to be confirmed by
BT SIG)
tx power calibration
4 (1 for each available power
level)
measured during ATE
Keyfob button timing diagrams for common scenarios.
Short press showing de-bouncing other buttons not pressed.
0) Button is pushed at time zero.
a) After de-bouncing button is determined as pressed but no message is generated.
b) After ‘short press minimum time’ a short press event is generated and if configured a
message is broadcast with button state 0b00000010 and reason code 0b00010001.
c) After ‘short press repeat time’ a short press repeat event is generated and if configured a
message is generated with button state 0b00000010 and reason code 0b00010001.
d) After Button is released and de-bounced a button release event is generated and if
configured a message is generated with button state 0b00000000 and reason code
0b00110001
0) Button 1 is pushed
a) Button 2 is pushed before ‘short press minimum time’ for button 1. Because button 2 is
pushed before ‘short press minimum time’ Buttons 1 and 2 are now considered as grouped
for the purposes of the reason code.
b) Short press minimum time elapses on both button 1 and 2 if configured a message is
broadcast with button state 0b00010010 and a reason code of 0b00010011
c) The short press repeat time passes for buttons 1 and 2; if configured a message is generated
with button state 0b00001010 and a reason code of 0b00010011.
d) button 2 is released if configured a message is generated with button state 0b00000010 and
reason code 0b00110010
e) Button 1 is released if configured a message is generated with button state 0b00000000 and
reason code 0b00110001
Button 1
0 a b c d
Button 1
Button 2
0 a b cccc d e
0) Button 1 is pushed
a) Button 1 ‘short press minimum time’; a short press event is generated and if configured a
message is broadcast with button state 0b00000010 and reason code 0b00010001.
b) Button 1 ‘short press repeat time’; a short press repeat event is generated and if configured
a message is generated with button state 0b00000010 and reason code 0b00010001.
c) Button 2 ‘short press minimum time’; a short press event is generated and if configured a
message is broadcast with button state 0b00001010 and reason code 0b00010010.
d) Button 1+2 ‘short press repeat time’; a short press repeat event is generated and if
configured a message is generated with button state 0b00001010 and reason code
0b00010011.
e) Button 2 ‘released’; a button release event is generated and if configured a message is
generated with button state 0b00000010 and reason code 0b00110010
f) Button 1 ‘short press repeat time’; a short press repeat event is generated and if configured
a message is generated with button state 0b00000010 and reason code 0b00010001.
g) Button 1 ‘long press time’; a long press event is generated and if configured a message is
generated with button state 0b00000011 and reason code 0b00100001.
h) Button 1 ‘long press repeat time’; a long press repeat event is generated and if configured a
message is generated with button state 0b00000011 and reason code 0b00100001.
i) Button 1 ‘released’; a button release event is generated and if configured a message is
generated with button state 0b00000000 and reason code 0b00110000.
LMU-FOB comms
Advertisement packet contents
The advertisement consists of at least 2 parts from GAP specification, Manufacturer Specific Data
called ‘calamp fob data’; and Tx Power Level called txpw.
Calamp Fob data contents
note: now using the MAC address as the fob ID.
size (bytes) Description default
L 1 length of this data 0x10
F 1 Manufacturer Specific Data as
defined in GAP
0xff
cal
2
Calamp manufacturer ID set by us
to distinguish our devices
0xca1a (big endian)
TBC
Button 1
Button 2
0 a b b b b c d e f g h h i
calamp fob data txpw
L F cal vcid pfv ccrc s r b a
v
1
version of this message
0x01
cid 2 Set by customer/provisioning to
allow a single customer to
differentiate their devices from
the mass.
0x0000
p 1 App id;for the keyfob this is 0x01 0x01
fv 2 Version of keyfob firmware
running on the keyfob.
0xnnbb (big endian)
nn coded as packed
binary coded decimal
bb is version letter
and running area (see
below)
0x1308 is version
“1.3e” running from
low area
c
1
configuration version
crc 2 crc of the keyfob configuration
(defined above) that will include
CID, button config etc . Actual crc
polynomial TBD. This is to be used
to determine if the configuration
is as expected.
N/A
s 1 button state (see above) 0x00 no buttons
pressed
r 1 advertisement old button state
captured in previous time slot(see
above)
0x00 beacon
b
1
battery state (%)
0x64 100%
a 1 RSSI @ 1 metre taking into
account tx power level
n/a
Version letter encoding
version letter
bb for low area
bb for high area
‘a’
0x00
0x01
‘b’
0x02
0x03
‘c’
0x04
0x05
‘d’ 0x06 0x07
......
‘y’ 0x30 0x31
‘z’ 0x32 0x33
txpw contents
size (bytes)
Description
default
L
1
length of this data
2
P 1 Tx power as defined in GAP 0x0a
p 1 transmitted power of this 0xf6 (-10dB) **TBD
L P p
advertisement (db)
Scan response packet contents
May contain uuids of services, name and any other static data.
Overview of Bluetooth Automatic Driver ID process
State Machine for driver ID discovery
To mitigate contention where a FOB is in range of several LMUs the LMU will only look for FOBs
when the PEG script executes PEG action.
State Machine for Finding Fobs using Beeps and Buttons
Description
• LMU is asleep saving power
• Key Fob(s) transmitting beacons (advertisement packets) every 10 seconds.
• Driver turns key in ignition (and wakes LMU)
Idle
Finding
Driver Fob
Fob
connected
Fob Found
PEG Trigger
PEG trigger
PEG Action
Out of Range or
PEG Action
Not Found
PEG Trigger
• Peg ignition trigger causes Peg BT_KEYFOB_DISCOVER action (TBD) for
BT_KEYFOB_DISCOVER_TIME (configurable TBD) time.
• BT middleware starts discovery
• BT middleware populates discovered devices list including FOB ID and RSSI and TxPwr for all
calamp keyfobs that match the BT_KEYFOB_CID (configurable 0-FFFE standard CID, FFFF is
special case).
• BT middleware stops discovery after BT_KEYFOB_DISCOVER_TIME timeout
• BT middleware calculates path attenuation for all discovered keyfobs based on RSSI and
TxPwr.
o If a single KeyFob has (config TBD) smaller path attenuation [BT_KEYFOB_PATHATT]
than all others, that key fob is selected as the driver’s fob.
o If a single KeyFob has advertised a button push that key fob is selected as the
driver’s fob.
o Otherwise a set of candidate fobs is created from those fobs within
BT_KEYFOB_PATHATT of the least attenuated.
if configured with BT_KEYFOB_USE_FOB_RSSI (config TBD) BT middleware
connects in turn to each candidate fob and uses a config/control service to
measure the RSSI at the fob
• If a single KeyFob measures the RSSI with a
6dB/BT_KEYFOB_PATHATT less than all the rest this fob is selected
as the driver’s fob.
otherwise if configured with BT_KEYFOB_USE_FOB_BUTT (config TBD) BT
Middleware connects to each candidate fob and requests the buzzer to
sound for TBD on bench, start with 200) ms. BT middleware waits for
BT_KEYFOB_QUERY_DRIVER_TIMEOUT (config TBD) for a button press
response from the driver.
• if button defined in BT_KEYFOB_USE_FOB_BUTT is received from a
single fob, this fob is selected as the drivers fob
otherwise the driver’s fob is set to null.
• if driver’s fob is non null
o BT Middleware invokes PEG TRIG_BLE_FOB (already used) trigger with a button code
(TBD) as the modifier; having populated (config TBD) ACC_BLE_RSSI_HILO (already
used) accumulator with RSSI and ACC_BLE_FOB_BATT (config TBD) (already used)
with battery status.
o BT Middleware invokes DID_DriverId_Event()(already used) with FOB ID (not MAC
address) as the driver’s ID
o BT Middleware connects to Drivers fob and connects to the ‘button notification’
service; the ‘LED’ service; the ‘Buzzer’ service; and the ‘Configuration’ service.
o button notification service provides the button state and reason codes as per
advertisement packet.
o while connected PEG actions ACT_KEYFOB_BUZZ (config TBD) cause BT-middleware
to connect to the buzzer service(TBD) and sound the buzzer according to the
modifier (TBD)
Comment [n1]:
Optional for phase 2
o while connected PEG actions ACT_KEYFOB_LED (config TBD) cause BT-middleware to
connect to the led service(TBD) and sound the buzzer according to the modifier
(TBD)
o While connected BT-middleware connects to config service(config TBD) and ota
management service(config TBD) and constructs a PULS ID report with the fob id as
the unique identifier and the LMU id as an agent(TBD).
o If required LMU will download new config or firmware for fob.
the BT-middleware will contact the config service to update the config as
necessary
the BT-middleware will contact the OTA service and update firmware as
necessary
the BT-middleware will restart the fob firmware using the keyfob
control(TBD) service
Note: no settings changes take effect without reset. Reset drops the
connection.
o BT-Middleware monitors the connection. If the connection drops BT-middleware
invokes PEG TRIG_BLE_FOB (already used) trigger and DID_DriverId_Event()(already
used)
Sequence diagram of discovery of driver id when only one fob in range
Sequence Diagram of discovery of driver ID using buzzer and button
Sequence diagram of connecting to a single fob to sound buzzer during driver id
discovery
Bluetooth LE services
Service Name
Attribute Name
r/w
size (bytes)
notes
LED
New custom primary service
pattern
r/w
3
Characteristic that defines the blink
pattern 1st byte on time; 2nd byte off
time; 3rd byte blink pattern least
significant bit first is shifted to the
LED; bit 1 implies on; LED turned off
at end of pattern
Buzzer New custom primary service
pattern r/w 3 as above
Button New custom primary service
button r 2 1
st
byte is the button state; 2
nd
byte is
the reason code identical to the
advertisement packet
Config/control
New custom primary service
Config
r/w
16
read write fob configuration
reset
w
1
write to reset keyfob
RSSI
r
8
RSSI of connection to LMU
OverAir
download
existing TI service
TBC
New PEG triggers
Trigger
Modifier
Description
PEG TRIG_BLE_FOB
PEG_MOD_FOB_BUTTON
Existing trigger new modifier
New Trigger modifiers
Modifier Description
PEG_MOD_FOB_BUTTON TBD probably the reason code
from advertisement with extra
for ‘fob out-of-range’ value
New PEG actions
Action Modifier Description
ACT_BT_KEYFOB 0 – DISCOVER/CONNECT
1 – HUP
Start discovery for a period of time
ACT_BT _LISTSEND
0NONE
send list of discovered keyfobs to server in
an app message
ACT_KEYFOB_OUTPUT B7-b6:
Output Dest
0 – LED
1 – BUZZER
B5-b4:
Pattern
0 – Slow 1Hz
1 – Fast 5Hz
B3-b0:
count
beep buzzer count (up to 4) times
None disconnect FOB
Params
size (bits) Desc
BT_KEYFOB_DISCOVER_TIME 16 Discovery time period (30)
BT_KEYFOB_CID
16
filter for customer’s keyfobs default (0x0000)
BT_KEYFOB_PATHATT 8 a single keyfob needs to have a greater RSSI
than all other discovered keyfobs; exceeding
by at least this configured amount
BT_KEYFOB_MODE 8 9 = USE_FOB_RSSI
10 = USE_FOB_BUTT
BT_KEYFOB_QUERY_DRIVER_TIMEOUT
8
1s/bit wait for this long to see button press
BT_KEYFOB_USE_FOB_BUTT 8 0-3 configures which button on the fob is
designated as the driver’s response button
ACC_BLE_RSSI_HILO 8 configure which accumulator holds RSSI of
driver’s fob
ACC_BLE_FOB_BATT
8
configure which accumulator holds battery
status of driver’s fob
Comment [n2]:
Use Existing Bluetooth Mode
configuration and have two enumerations for FOB
use, 1 for Use FOB RSSI and 1 for Use FOB BUTT
Comment [n3]:
NF check understanding. Should
have new accumulator type BLE_RSSI.
Comment [n4]: As per comment above.
Driver’s FOB Out-of-Range
‘Disconnect’ from BTCS is used to signal to LMU that driver’s ID is no longer valid.
option 1) New/existing Peg trigger to allow peg to decide to rescan () and send a logoff message to
server.
option 2) If Ignition is still on, rescan automatically and follow driver ID discovery process.
option 3) Both of the above
Over the Air Update
Note that it is possible that a different fob could be connected after an OTA upgrade, and so the next
ID report for the upgraded fob will not be until the next time it is used.
Generated (https://www.websequencediagrams.com/#):
For Style: use “Plain UML” style.
title OTA Sequence
Fob->LMU: Advertisement Packet with Fob version
note right of LMU: Connection algorithm determines\nthat it should connect to this Fob
LMU->Fob: Connect
LMU->Server: Fob OTA ID Report
note right of Server: Checks fob's version against any queued\nupdates and determines if one is
available
Server->LMU: OTA Download available (App 107)
note right of LMU: Check if have file already in OTA\n flash storage.
LMU<->Server: HTTP download of A&B image (if required)
note right of Fob: FOB new version is captured
LMU<->Fob: OAD update of A/B image
note left of Fob: Validate image, reset and run
Fob->LMU: Advertisement Packet with new Fob version
note right of LMU: Connection algorithm determines\nthat it should connect to this Fob
LMU->Fob: Connect
LMU->Server: Fob OTA ID Report
note right of Server: If this is the same fob then confirms version\nis updated and marks OTA as
complete
note right of Server: Checks fob's version against any queued\nupdates and determines if one is
available
Format of Fob OTA ID report
This is the LM Direct ID report for the Bluetooth fob that is sent from the LMU to PULS.
The PULS ID report for the Bluetooth fob will use LM Direct Message type 13 which is a Device
Version Report Message. This message type was created for the Android MDT but can be reused by
changing the device type in the message body.
7
0
Options Header (optional)
…
Message Header
…
JSON Object
…
Device Version Report Message Format
The message body (following the Message Header) consists of a single JavaScript Object Notation
(JSON) object, which for the fob will contain three JSON structures. The names and contents of each
structure are summarized in the table below:
Name JSON
type
Contents
“ids” array Device type for Bluetooth fob (13),
Hardware version (key fob app id = 1),
MAC ID,
Firmware file type (0),
Firmware version
Name JSON
type
Contents
“extensions” object "OTA":”<protocols>|<device type>;<supported file types>”,
"OTASTAT":”<OTA ID>,<device type>,<file type>,<state
code>,<diagnostic code>,<additional status>”
“which” array The number of this message (starting from 1),
the number of messages in the report
The OTA ID field in the OTASTAT value is initialised to 00000000 and updated when any App 107
message is received.
The OTASTAT value will be reset to “00000000,13,0,0,0,” at initialisation and for any fob ID report to
PULS where the MAC ID does not match the previous (if any) fob ID report to PULS.
An example of the JSON object is:
{“ids”:[13,1,”D05FB80DE12F”,0,”1.0a”],”extensions”:{"OTA":"1|13;0","
OTASTAT":"00000000,13,0,0,0,"},"which":[1,1]}
Note that the order within JSON arrays is fixed, but the order in JSON objects is not fixed, and so for
example the “ids” member is not necessarily the first member, and within the “extensions” object
the “OTASTAT” name/value pair may precede the “OTA” name/value pair.
The example above decodes as follows:
Structure Type Value or Name:Value Explanation
ids array 13 Device type for Bluetooth fob
1 Hardware version is the key fob app id
”D05FB80DE12F” MAC ID
0 Firmware file type
“1.0a” Firmware version
extensions object "OTA":"1|13;0" OTA attributes:
supported protocols = 1 (HTTP)
Device type = 13 (Bluetooth fob)
Supported file types = 0 (Firmware)
OTASTAT":"00000000,13,0,0,0," OTA status:
OTAID = 00000000 (timestamp)
Device type = 13 (Bluetooth fob)
File type = 0 (Firmware)
State code = 0
Diag code = 0
Additional status = “” (none)
which array 1 This is message 1
1 Number of messages in report is 1
Work Breakdown
Build Process
Firmware Version
Make sure that the build process automatically names the final binaries correctly and that there is
exactly one place in the project that sets the version information.
Keyfob
Keyfob Over the air service
we are currently working on this.
Keyfob Advertisement packet
Fully populate with at least static data
Keyfob Button push advertisement
This includes different advertisement timing; detection of button states; and reason coding.
Keyfob configuration storage (done?? or only ATE)
Keyfob Config service
Keyfob measure rssi service/characteristic
This is measuring the rssi of the LMU/BTCS transmissions on the keyfob
Keyfob LED service
Keyfob Buzzer service
This should be implemented as a carbon copy of LED service reusing code as much as possible.
BTCS
ATDILE
ATDMLE
ATGDCU
LMU
LMU Over the air BT Client
??? what is needed ???
LMU Modified interaction with Puls new FOB_ID message
Includes designing the contents of this message and pretty documentation
LMU Modified ‘file’ Handling to allow LMU to ‘cache’ file.
LMU Keyfob config ??? Puls or params?
LMU passive scan for strongest keyfob
Includes creating a list of ‘seen’ keyfobs; adding parameters BT_KEYFOB_CID,
BT_KEYFOB_DISCOVER_TIME; adding PEG action ACT_BT_KEYFOB_DISCOVER.
LMU report of ‘seen keyfobs’
Includes PEG action ACT_BT_KEYFOB_LISTSEND to generate the report and pretty documentation of
the report contents.
LMU selection of keyfob by measuring rssi on the key fob
Includes state machine to connect to each candidate keyfob and request RSSI measurement.
LMU selection of keyfob by beep and button on the key fob
Includes state machine to connect to each candidate keyfob and beep buzzer then wait for response.
LMU PEG trigger PEG TRIG_BLE_FOB
Trigger is done make needs to be integrated with new feature; add new button modifier.
LMU PEG action ACT_KEYFOB_BUZZ
Add new peg action
LMU PEG action ACT_KEYFOB_LED
Add new peg action
LMU PEG action ACT_ BT_KEYFOB_HUP
Add new peg action to disconnect from current driver’s fob

Navigation menu