Welcome to LEGO Wireless Protocol 3.0.00 documentation!¶

1. Introduction¶

The LEGO Bluetooth 3.X Hub Profile consists of a single Bluetooth LE GATT service. The service allows users to read info about the LEGO Hub (name, battery level, etc.) and to interact with any sensors and motors connected to it.

For more details on Bluetooth LE GATT, visit <https://www.bluetooth.org>.

1.1. Versions¶

Bluetooth Hub Profile (this document): XX

Implemented in LEGO Hub Firmware: XX

Implemented in LEGO Hub SDK: XX

1.2. Glossary¶

Term	Description
Brake	When the motor is shorted through the motordriver.
Central	A LEGO BLE H/W only Network will always have 1 Central and a number of Peripherals. If a Smart Device (e.g. an iPad) is used, this will always have the Central role.
Client	NOT USED! No real client/server connection.
Coast	Another word for a free running motor (float)
Combined Mode	Indicates whether the Modes of a given Port can be used as a group to get mutliple values at once
CombinedSensor	A sensor able to have more Mode/Dataset combinations. e.g. the LPF2 Vision Sensor
Dataset	Dataset represents a portion of sensor output in a given mode. e.g. RGB sensor has 3 Datasets - one each for RGB
Device	NOT USED! Ambiguous meaning
Drift	Another word for a free running motor (float)
Drive	Another word for 2 syncronized/regulated motors
Drive Base	An intelligent Brick with 2 built in synchronized motors
Float	Another word for an inactive port. I.e. NO power power supplied to a motor (high impedance).
Hold	When the motor is stopped (no rotation/movement), but the driver continues to keep the current position by actively
Hub	A LEGO Bluetooth LE compatible Hub
LPF2 Device	Physical or Virtual sensor/actuator connected to a Hub
Master	NOT USED! Can be mixed up with the Central/ Peripheral role, so NOT used. Misused even in some H/W datasheets
Max-Power	Max-Power describes the upper power limit for speed commands. Max-Power sets the maximum power that the regulation is allowed to use while trying to maintain a certain speed.
Mode	A Mode is a Port feature, allowing the Port to operate in different ways.
Peripheral	LEGO hub connected to a Central Role hub or Smart Device
Power	Is the word used when applying power to an output port (e.g. a motor). Power is different from Speed, in that it is unregulated, and thereby only sets the PWM Duty Cycle for the output. All LPF2 motors and hubs support power commands.
Server	NOT USED! No real client/server connection.
Slave	NOT USED! Can be mixed up with the Central/ Peripheral role, so NOT used.Misused even in some H/W datasheets.
Speed	Is the word used when applying speed to an output (normally a tacho-motor). Speed is regulated, which means that the hub will control the power to the motor and hence it can maintain a given speed.
Steering	Another word for regulated/synchronized motors.
Synchronization	The act of joining two Ports into a Virtual Port. e.g. The 2 internal motors of a drivebase.
Virtual Port	Port resulting from synchronizing two Ports
Virtual Sensor	A sensor delivering the (logical) average of two sensor. e.g A virtual sensor representing the average tacho counts from 2 synchronized motors (acting as a drivebase).

2. Advertising¶

When in Advertising mode, a LEGO BLE compatible device fills in the message with its friendly name (as described in Properties) along with up to n sequential bytes of Manufacturer Data.

The Manufacturer Data is filled in according to the table below:

Manufacturer Data

Name Description Offset Format Min Max

Length Length of data 0 UINT8 0x09 0x09

Data Type Name Manufacturer specific data to follow 1 UINT8 0xFF 0xFF

Manufacturer ID Manufacturer identifier 2 UINT16 0x0397 0x0397

Button State Reflects the state of the device button 4 UINT8 0 1

System Type and Device Number Identifies the system type of the Hub 5 UINT8 0x00 0xFF

Device Capabilities Describes the capabilities of the device 6 UINT8 0x01 0xFF

Last network Network ID of the last network 7 UINT8 0 255

Status Actual status 8 UINT8 0 255

Option Future use 9 UINT8 0 255

2.1. System Type and Device Number¶

Encoded as 2 bit-fields in one byte SSS DDDDD

The System Type contained in the leftmost bits is interpreted as:

SSS Description

000 LEGO Wedo 2.0

001 LEGO Duplo

010 LEGO System

011 LEGO System

The Device Number in the rightmost bits represents the unique identifier for a product within a System Type. The currently available LEGO BLE compatible devices are:

SSS DDDDD Description

000 00000 WeDo Hub

001 00000 Duplo Train

010 00000 Boost Hub

010 00001 2 Port Hub

010 00010 2 Port Handset

2.2. Device Capabilities (Hub Kind)¶

Encoded as a bit-field CCCC CCCC

A LEGO BLE compatible device has capabilities, but not all devices have the same capabilities.

CCCC CCCC Description

0000 0001 Supports Central Role

0000 0010 Supports Peripheral Role

0000 0100 Supports LPF2 devices (H/W connectors)

0000 1000 Act as a Remote Controller (R/C)

0001 0000 TBD

0010 0000 TBD

0100 0000 TBD

1000 0000 TBD

2.3. Last Network ID¶

The Last Network ID is used in the LEGO BLE device pairing process.

000: NONE (unknown)

001..250: The ID’s used for “Last Connection” Network ID’s. Used in H/W network “auto connect”

251: DEFAULT 1, Locked

252: DEFAULT 2, NOT Locked

253: DEFAULT 3, RSSI Dependent

254: DEFAULT 4, DISABLE H/W Network

255: DON’T CARE - NOT Implemented

2.4. Status¶

Encoded as a bit-field SSSS SSSS

`SSSS SSSS`	Description
0000 0001	“I can be Peripheral”
0000 0010	“I can be Central”
0000 0100	TBD
0000 1000	TBD
0001 0000	TBD
0010 0000	“Request Window” A stretching of the Button Pressed (Adding 1 sec. after release) [part of connection process]. See Request Window
0100 0000	“Request Connect”. Hardcoded request (i.e. CONSTANT flag)
1000 0000	TBD

2.4.1. Request Window¶

The “Connect from poweron” will be delayed, as long as the user hold down the connection button. On the central, the button pressed from powerup is also used for detecting “Go into bootloader mode” or “The clear last connection table”. This is why the connection request on the central is measured/sampled from the button release. The pulse-stretching bit will be held set for 1000 mS. after the release of the Connection Button. For more information about userinterface see the LPF2 Platforms document.

2.5. Future Option Byte(s)¶

000..255: TBD

3. LEGO Specific GATT Service¶

The LEGO Bluetooth 3.X Hub Profile contains the following service:

Service	UUID
LEGO Hub Service	00001623 -1212-EFDE-1623-785FEABCD123

Due to potential limitations in future BLE chipsets, the LEGO Service only contains one single characteristic:

Characteristic	UUID
LEGO Hub Characteristic	00001624 -1212-EFDE-1623-785FEABCD123

The <1624> LEGO Hub Characteristic Supported Properties
Property	Description
Write without response ^[1]	Allows users to use the Write Command ATT operation on this characteristic.
Notify	Allows the user to use the Handle Value Notification ATT operation on this characteristic.

^[1]See Transmission Flow Control (Preliminary PROPOSAL!) - UNTIL IMPLEMENTED, the write will be Write With Response (Apple IOS stuff).

Note, that throughout the remainder of this documentation, these UUIDs will be referenced by their short form (the part marked in bold).

Thus, since all attributes and properties are accessed through a single characteristic, the notion of updates is introduced to clearly distinguish these from standard characteristic notifications. Furthermore, with only a single characteristic available, communicating with the Hub as of Hub Profile 3.X and onwards is not done the usual way, when it comes to the use of services and characteristics. Normally, each attribute/property has its own characteristic, but with the limitation of only a single characteristic, these attributes/properties are now identified through a Message Type field included in a Common Header described below:

3.1. Common Message Header¶

LEGO Hub Characteristic (UUID: 1624) - Common Header

Communication:

Size:

Description:

Length:

Hub ID:

Downstream + Upstream

3 Bytes

Common Header for all messages in the LEGO Hub Characteristic.

Introduced to be independent of the MTU in the transport layer.

Handle to a Hub node in a H/W network - stand-alone networks without a Smart Device.

Header format - see below.

Header Format:
Name:	Description:	Format:	Min:	Max:
Length	Length of entire message in bytes (escaped and 2 bytes for long messages) For further information about encoding - see Message Length Encoding	Uint8 (Uint7) /Uint16	N/A	N/A
Hub ID NOT USE at the moment! Always set to 0x00 (zero)	Hub identifier is needed when a Hub is connected as a bridge to a network formerly build without a SMART DEVICE. E.g. HUB A is connected to HUB B and HUB C is added. After a while the SMART DEVICE is connected to the network. HUB A is now acting as a Central for B and C while acting as a Peripheral to the SMART DEVICE. Data from B and C will be routed through HUB A.	Uint8	0	255
Message Type	Identifies the kind of message transmitted. For message types - see Message Types	Uint8	0	0xXX

3.2. Message Length Encoding¶

Messages having a length of 1 to 127 bytes is represented in 1 byte. For messages above 127, the 1 byte encoding is escaped and 2 bytes is used - i.e. if bit 7 in the very first byte is set, the following byte (2’nd) should also be used for en-/decoding the length. Hence the LSB (1st byte) can only be used as 7 bit. Lengths greater than 127 are therefore represented as:

Message Length Encoding
LSB:	MSB:
1000 0000	0000 0001 = 128
1000 0001	0000 0001 = 129
1000 0010	0000 0001 = 130

3.3. Message Types¶

The table below summarizes the various Message Types introduced. These will be described in detail in the following sections.

Message Type Definitions - HUB related
Message Type definitions available for the LEGO Hub Characteristic (0x1624)
Name	Value	Comm.	Reply to	Notes
Hub Properties	0x01	Down + Up	0x01	Set or retrieve standard Hub Property information
Hub Actions	0x02	Down + Up	0x02	Perform actions on connected hub
Hub Alerts	0x03	Down + Up	0x03	Subscribe or retrieve Hub alerts
Hub Attached I/O	0x04	Up	N/A	Transmitted upon Hub detection of attached I/O
Generic Error Messages	0x05	Up	N/A	Generic Error Messages from the Hub
H/W NetWork Commands	0x08	Down + Up	0x08	Commands used for H/W Networks
F/W Update - Go Into Boot Mode	0x10	Down	N/A	Set the Hub in a special Boot Loader mode
F/W Update Lock memory	0x11	Down	N/A	Locks the memory
F/W Update Lock Status Request	0x12	Down	N/A	Request the Memory Locking State
F/W Lock Status	0x13	Up	0x12	Answer to the F/W Lock Status Request

Message Type Definitions - PORT(s) related
Message Type definitions available for the LEGO Hub Characteristic (0x1624)
Name	Value	Comm.	Reply to	Notes
Port Information Request	0x21	Down	N/A	Request Port information
Port Mode Information Request	0x22	Down	N/A	Request Port Mode information
Port Input Format Setup (Single)	0x41	Down	N/A	Setup input format for single mode
Port Input Format Setup (CombinedMode)	0x42	Down		Setup input format for multiple modes (CombinedMode)
Port Information	0x43	Up	0x21	N/A
Port Mode Information	0x44	Up	0x22	N/A
Port Value (Single)	0x45	Up	0x21	Value update related to single Port Mode
Port Value (CombinedMode)	0x46	Up	0x21	Value update related to multiple Port Modes in combination (CombinedMode)
Port Input Format (Single)	0x47	Up	0x41	N/A
Port Input Format (CombinedMode)	0x48	Up	0x42	N/A
Virtual Port Setup	0x61	Down	N/A	Used to control synchronization between synchronizable ports.
Port Output Command	0x81	Down	N/A	Used to execute Port Output commands
Port Output Command Feedback	0x82	Up	0x81	Provides feedback on completed Port Output commands

3.4. Transmission Flow Control (Preliminary PROPOSAL!)¶

Warning

In order to allow a safe and lossless transmission over Bluetooth Low Energy (IOS) we have to add some delivery check. We still want fast response for small control messages. Using a sequence number will let us known if messages are missing, but having the same knowledge at both sender and receiver will slow down the overall throughput. Using a prioritized ack-/nack protocol could be a compromise. The priority counter could be as simple as only 1 bit.

Sequence and priority counter: PPPS SSSS - P = Priority counter bits (0-7) S = Sequence counter (0-31-0)

Sender:		Receiver:	Ack/Nack counter:
010	00001	01000001	01000001
001	00010	00100010	00100010
000	00011	00000011	000 => Send ACK 00011

000	11000	00011000	000 => Send ACK 11000 // FAST

011	11011	01111011	01111011
010	11100	01011100	01011100
001	11101	???????	01011100 // Still
000	11110	00011110	01011100 => Send NACK 11100

3.5. Hub Properties¶

Message Type - Hub Properties [0x01]

Communication:

Size:

Description:

Downstream + Upstream

5 Bytes + Payload

This message allows access and control of the various different properties of the Hub. The message introduces the notion of Updates. This term coins the various different data which the Hub is capable of delivering. Note, that all the data updates are controlled by the Notify property of the LEGO Hub Characteristic.

If notifications are disabled, not a single update will be delivered.

Since not all operations apply for all properties of the hub, the following table seeks to identify valid combinations as well as indicating which data is part of the downstream message, and vice versa.

3.5.1. Hub Property and Operation¶

Property	Operation
	Set	Enable Update	Disable Update	Reset	Req. Update	Update
Adv. Name	X	X	X	X^[2]	X	X
Button		X	X		X	X
FW Version					X	X
HW Version					X	X
RSSI		X	X		X	X
Battery Voltage		X	X		X	X
Battery Type					X	X
Manufacturer Name					X	X
Radio Firmware Version					X	X
LWP ^[3] Protocol Version					X	X
System Type ID					X	X
H/W NetWork ID x	X			X	X	X
Primary MAC address					X	X
Secondary MAC address					X	X
H/W Network Family	X				X	X

^[2] Resetting the Adv. Name will automatically insert the DEFAULT NAME

^[3] LWP = LEGO Wireless Protocol

3.5.2. Hub Property Message Format¶

Message Format
Name	Description	Format	Min	Max
Common Header	See Common Message Header for header format	N/A	N/A	N/A
Property	Identifies the Hub Property Operation subject to the performed operation:	Uint8	0x01	0x0F
Operation	Identifies the type of Hub Property Operation performed:	Uint8	0x01	0x06
Payload	The Hub Property Payload. Note, Common Header Length field governs the length of the payload.	Uint8[?]	N/A	N/A

3.5.3. Hub Property Reference¶

Property Reference [UInt8]	Property Name
0x01	Advertising Name
0x02	Button
0x03	FW Version
0x04	HW Version
0x05	RSSI
0x06	Battery Voltage
0x07	Battery Type
0x08	Manufacturer Name
0x09	Radio Firmware Version
0x0A	LEGO Wireless Protocol Version
0x0B	System Type ID
0x0C	H/W Network ID
0x0D	Primary MAC Address
0x0E	Secondary MAC Address
0x0F	Hardware Network Family

3.5.4. Hub Property Operation¶

Property Operation
0x01	Set (Downstream)
0x02	Enable Updates (Downstream)
0x03	Disable Updates (Downstream)
0x04	Reset (Downstream)
0x05	Request Update (Downstream)
0x06	Update (Upstream)

3.5.5. Hub Property Payload¶

Property Payload
Property ref:	Direction Up-/Downstream:	Description	Format	Min	Max
0x01	Upstream/Downstream	Advertising Name^[A]	UInt8[MAX_NAME_SIZE]	1 char	MAX_NAME_SIZE ^[B]
0x02	Upstream	Button State TRUE/FALSE [0x01/0x00]	UInt8	0x00	0x01
0x03	Upstream	FW Version encodes as: Version Number Encoding	Int32^[C]	N/A	N/A
0x04	Upstream	HW Version encodes as: Version Number Encoding	Int32^[C]	N/A	N/A
0x05	Upstream	RSSI^[D]	Int8	-127	0
0x06	Upstream	Battery Voltage [%]	UInt8	0x00	0x64
0x07	Upstream	Battery Type: [Normal/Rechargable]	UInt8	0x00 Normal Battery type	0x01 Rechargeable block
0x08	Upstream	Manufacturer Name LEGO System A/S	Uint8[] “LEGO System A/S”	UInt8[15]	UInt8[15]
0x09	Upstream	Radio Firmware Version as a string. E.g. “7.1e”	Uint8[]	UInt8[15]	UInt8[15]
0x0A	Upstream	LWP Protocol Version Encoded as LWP Version Number Encoding	UInt16	0x0100	0x9999
0x0B	Upstream	System Type ID^[E] See System Type and Device Number for info.	UInt8	N/A	N/A
0x0C	Upstream	H/W NetWork ID^[F] See Last Network ID for info.	UInt8	0x01	0xFA (250)
0x0D	Upstream	Primary MAC address^[G] This is the MAC address used when the normal application runs on the BLE device.	6 Bytes	N/A	N/A
0x0E	Upstream	Secondary MAC address^[G] The MAC address used for the Boot Loader task.		N/A	N/A
0x0F	Upstream	H/W Network Family [0-8]. Used in conjunction with H/W Net- work ID to configure H/W stand- alone networks. E.g. In an education setup.	UInt8	0x00	0x08

^[A] This is also the name which is placed in the Advertising Response packet.

^[B] MAX_NAME_SIZE = 14 Chars (Packet limitations)

^[C] Sint32 is a leftover from earlier version numbering schemes.

^[D] RSSI (Received Signal Strength Indicator) is the RF-level measured at receiving device. This level depends of distance, transmitted power and obstacles in the “line of sight”. Not a “real” calibrated dBm, but a less negative number still equals a higher and better signal level.

^[E] System Type ID is also advertised by both the normal application and the Boot Loader. Used when the HUB or other BLE device doesn’t have an image - i.e. this property can’t be accessed. See System Type and Device Number for encoding.

^[F] When unconnected this is the number transmitted as Last Network in the Advertising Packet.

^[G] Some operating systems uses the MAC address for persistent reference and hence different Services can not be interleaved randomly. By using a different MAC address as well as a different UUID for the services, these operating systems will see two different services while advertising goes on (different MAC addresses). The MAC addresses is represented as a multibyte array - BIG Endianness.

3.5.6. Version Number Encoding¶

All version numbers are encoded into a 32 bit Signed Integer [Little Endianness]: 0MMM mmmm BBBB BBBB bbbb bbbb bbbb bbbb

Version Number Encoding
`####`	Description	Format (position)	Min	Max
`0MMM`	Major version - upper 4(3) bits of byte 3	0MMM ????	0x0?	0x7?
`mmmm`	Minor version - lower 4 bits of byte 3	???? mmmm	0x?0	0x?9
`BBBB BBBB`	Bug fixing number	Byte 2	0x00 [BCD]	0x99 [BCD]
`bbbb bbbb bbbb bbbb`	Build Number	Byte 1 and Byte 0 (unsigned SHORT)	0x0000 [BCD]	0x9999 [BCD]

As an example 1.7.37.1510 is encoded as shown below: (Numbers normally presented at user-level is shown in bold)

These are encoded in the 4 bytes as:

Byte 3 (MSB): 0x17 (Presented at user-level)

Byte 2: 0x37 (Presented at user-level)

Byte 1: 0x15

Byte 0 (LSB): 0x10

3.5.7. LWP Version Number Encoding¶

The LWP Protocol Version is encoded in a single UInt16 as BCD. MMMM MMMM mmmm mmmm

LWP Version Number Encoding (LEGO Wireless Protocol)
`#### ####`	Description	Format (position)	Min	Max
`MMMM MMMMM`	Major version - upper 8 bits	Byte 1	0x01	0x99
`mmmm mmmm`	Minor version - lower 8 bits	Byte 0	0x00	0x99

3.6. Hub Actions¶

Message Type - Hub Actions [0x02]

Communication:

Size:

Description:

Downstream + Upstream

4 Bytes

This message allows for performing control actions on the connected Hub. Some of the controlling downstream actions, will trigger upstream updates from the hub.

3.6.1. Hub Action Message Format¶

Hub Action Message Format
Name	Description	Format	Min	Max
Common Header	See Common Message Header	N/A	N/A	N/A
Action Types	Identifies the property subject to the performed operation:	Uint8	0x01	0x32

3.6.2. Action Types¶

Downstream (reserved 0-0x2F)
Action Type	Description
0x01	Switch Off Hub
0x02	Disconnect
0x03	VCC Port Control On
0x04	VCC Port Control Off
0x05	Activate BUSY Indication (Shown byRGB. Actual RGB settings preserved).
0x06	Reset BUSY Indication (RGB shows the previously preserve RGB settings).
…
…
0X2F	Shutdown the Hub without any up-stream information send. Used for fast power down in production. Suggested for PRODUCTION USE ONLY!

Upstream (reserved 0x30-0x64)
Action Type	Description
0x30	Hub Will Switch Off
0x31	Hub Will Disconnect
0x32	Hub Will Go Into Boot Mode
…

3.7. Hub Alerts¶

Message Type - Hub Alerts [0x03]
Communication: Size: Description:	Upstream and Downstream
	Upstream	5 bytes
	Downstream	6 Bytes including the “Boolean” Alert Payload
	This message allow for subscribing to Hub alerts as well requesting current state of these.

3.7.1. Hub Alert Message Format¶

Hub Alert Message Format
Name	Description	Format	Min	Max
Common Header	See Common Message Header	N/A	N/A	N/A
Alert type	Identifies the property subject to the performed operation:	Uint8	0x01	0x04
Alert Operation	The operation to perform on the specified property	Uint8	0x01	0x04

3.7.2. Alert type¶

Hub Alert Types
Alert Type	Description
0x01	Low Voltage
0x02	High Current
0x03	Low Signal Strength
0x04	Over Power Condition

3.7.3. Alert Operation¶

Hub Alert Operations
Alert Operation	Description
0x01	Enable Updates (Downstream)
0x02	Disable Updates (Downstream)
0x03	Request Updates (Downstream)
0x04	Update (Upstream)

3.7.4. Alert Payload¶

Hub Alert Message Payload in upstream direction
Alert Payload	Description
0x00	Status OK
0xFF	Alert!

3.8. Hub Attached I/O¶

Message Type - Hub Attached I/O [0x04]
Communication:	Upstream
Size:	5 Bytes	(Detached I/O)
	15 Bytes	(Attached I/O)
	9 Bytes	(Attached Virtual I/O)
Description:	This message allow for subscribing to Hub alerts as well as requesting current state of these. REMARK: Current running implementations (primo 2018) will only send this message for Virtual Ports at the very first Attached IO message. If Virtual Port Setup [0x61] is called later the move-bases and HUBs will incorrectly send an error upstream. Should just reply with the already (implicit) set port IDs.

3.8.1. Hub Attached I/O Message Format¶

Hub Attached I/O - Message Format
Name	Description	Format	Min	Max
Common Header	See Common Message Header	N/A	N/A	N/A
Port ID	The Port ID associated with the Attached I/O assigned by the Hub	UInt8	0	Port ID
Event	IO de- and attachment events	UInt8	0x00	0x02
Below IO Type ID only for the Attached I/O and Attached Virtual I/O
IO Type ID	Unique type identification of the attached I/O device.	UInt16	0x0000	0xFFFF
Below only set if Event = Attached I/O
Hardware Revision	The hardware revision of the I/O Four bytes: {major, minor, bugfix, buildno} See Version Number Encoding:	Int32	N/A	N/A
Software Revision	The software revision of the I/O Four bytes: {major, minor, bugfix, buildno} See Version Number Encoding:	Int32	N/A	N/A
Below only set if Event = Attached Virtual I/O
Port ID A	The first Port ID forming the Virtual I/O	Uint8	N/A	N/A
Port ID B	The second Port ID forming the Virtual I/O	Uint8	N/A	N/A

3.8.2. Port ID¶

Port ID
ID range	Description
000 - 049	Hub connector (0, 1, 2 .. 49)^[##]
050 - 100	Internal
101 - 255	Reserved

^[##] Port IDs 0x00 - 0x0F used by HardWare Functional Mapping.

3.8.3. Event¶

I/O Event
Event	Description
0x00	Detached I/O
0x01	Attached I/O
0x02	Attached Virtual I/O

3.8.4. IO Type ID¶

IO Type IDs
Below mentioned IDs are the ones known at release of this document. Hence these IDs are only mentioned as a user- friendly reference. List NOT guaranteed up to date!
Type ID	Description
0x0001	Motor
0x0002	System Train Motor
0x0005	Button
0x0008	LED Light
0x0014	Voltage
0x0015	Current
0x0016	Piezo Tone (Sound)
0x0017	RGB Light
0x0022	External Tilt Sensor
0x0023	Motion Sensor
0x0025	Vision Sensor
0x0026	External Motor with Tacho
0x0027	Internal Motor with Tacho
0x0028	Internal Tilt

3.9. Generic Error Messages¶

Message Type - Error Messages [0x05]

Communication:

Size:

Description:

Upstream

5 Bytes

Generic Errors (also informative feedback e.g. ACK) messages. Definitions of the error types are listed at Error Codes. Errors messages includes the command ID which intro- duced the error or the ACK (message).

The Overcurrent (0x07) is send when an already stalled output is issued another active output command. I.e. telling the user that the command will not be executed due to the Overcurrent of the stalled output port.

The Internal ERROR should never occur - only triggered if internal functionality fails. Wrong command and/or wrong parameters are signaled as 0x05 and 0x06

3.9.1. Error Message Format¶

Error Message Format
Name	Description	Format	Min	Max
Common Header	See Common Message Header	N/A	N/A	N/A
Command type	The Command which has introduced this message. See the definitions in this document if Error is 0x05 the Message Type will of course be an invalid Message token.	UInt8	0x01	0xFF
Error Codes	The error introduce by the above mentioned command	UInt8	0x01	0x08

3.9.2. Error Codes¶

Error codes
Error code	Error Description
0x01	ACK
0x02	MACK
0x03	Buffer Overflow
0x04	Timeout
0x05	Command NOT recognized
0x06	Invalid use (e.g. parameter error(s)
0x07	Overcurrent
0x08	Internal ERROR

3.10. H/W NetWork Commands¶

Message Type - H/W Network Commands [0x08]
Communication:	Upstream and Downstream
Size:	Connect Request (upstream)	5 Bytes
	Family Request (upstream)	4 Bytes
	Family Set (downstream)	5 Bytes
	Join Denied (downstream)	4 Bytes
	Get Family (downstream)	4 Bytes
	Family (upstream)	5 Bytes
	Get SubFamily (downstream)	4 Bytes
	SubFamily (upstream)	5 bytes
	SubFamily Set New (downstream)	5 bytes
	Get Extended Family (downstream)	4 bytes
	Extended Family (upstream)	5 bytes
	Extended Family Set New (downstream)	5 bytes
	Reset Long Press Timing (downstream)	4 bytes
Description:	These commands are ONLY used for HardWare NetWork connectivity. I.e. Network without a Smart Device (e.g. IPad, IPhone etc.). The commands are used for setting up, routing connection commands and disconnecting devices from a H/W only network.
	Connection Request: [UpStream]	This message is used to route/gate a connection request from a peripheral device up to the con- trolling Central device. The user should be able to press the button on any devices in the current connected network for requesting a connection. Both the Pressed and the Release is send.
	Family Request: [UpStream]	When send upstream (from any device in the H/W network) this message is a request for a new Family and SubFamily, if possible.
	Family Set New: [DownStream]	This command is send from the controlling Central device and has the new Family added as payload.
	Join Denied: [DownStream]	This command is send to a peripheral trying to connect to a network where the maximum of nodes is reached (i.e. NO further connections available).
	Get Family: [DownStream]	Requesting the previous used Family for a specific (the addressed) device, just entered a network - NO family decided yet.
	Family: [UpStream]	This is the answer returned for above command (Get Family 0x06). Used by the Central Role device to decide the Family at auto connection.
	Get SubFamily: [DownStream]	Requesting the previous used SubFamily (Function) on a specific (addressed) device. E.g. a 2 port R/C to a 4 port hub. I.e. addressing a specific port (A+B or C+D)
	SubFamily: [UpStream]	This is the answer returned for above command (Get SubFamily 0x08). Used by the Central Role device to decide the SubFamily at auto connection.
	SubFamily Set New: [DownStream]	This command is send from the controlling Central device and has the new SubFamily added as payload.
	Get Extended Family: [DownStream]	Requesting the previous used Family and SubFamily for a specific (the addressed) device. The user can get both the Family and the SubFamily in one tx/rx. Further both are only using 3 bits for the addressing leaving one bit each for future use and/or escape.
	Extended Family: [UpStream]	This is the answer returned for above command (Get Extended Family 0x0A).
	Extended Family Set New: [DownStream]	The user can set both the Family and the SubFamily in one tx/rx. Further both are only using 3 bits for the addressing leaving one bit each for future use and/or escape (extended use).
	Reset Long Press Timing: [Down Stream]	The timing of the user CONNECTION PRESS may be stretched (timer reset) when connecting in a Bluetooth active environment. I.e. the LONG PRESS normally is used for powering down a device, but also used for gating keypresses to the Central in a connection sequence (allowing a longer connec- tion time without povering down.

3.10.1. H/W NetWork Message Format¶

H/W NetWork Message Format
Name	Description	Format	Min	Max
Common Header	See Common Message Header	N/A	N/A	N/A
H/W NetWork Command Type	Hardware Network command token	UInt8	0x02	0x0E
H/W NetWork Command Type = 0x02 Connection Request [Upstream]
Connection Request Payload	Button State: Pressed = 0x01 Released = 0x00	UInt8	0x00	0x01
H/W NetWork Command Type = 0x04 Family Set New [Downstream]
New H/W NetWork Family payload	The New H/W NetWork Family from controlling Central Device	Uint8	0x01	0x08
H/W NetWork Command Type = 0x07 “Family” [Upstream]
H/W NetWork Family payload	Family 0-8 (0), encoding see H/W NetWork Family	Uint8	0x01	0x08
H/W NetWork Command Type = 0x09 SubFamily [Upstream]
H/W NetWork Sub-Family payload	SubFamily 1-7, encoding see H/W NetWork Sub-Family	Uint8	0x01	0x07
H/W NetWork Command Type = 0x0A SubFamily Set New [Downstream]
New H/W NetWork Sub-Family payload	The New H/W NetWork Sub-Family from controlling Central Device.	Uint8	0x01	0x07
H/W NetWork Command Type = 0x0C Extended Family [Upstream]
H/W NetWork Extended Family payload	Command used to get both the H/W NetWork Family 0-8 and H/W NetWork Sub-Family 1-7 in one single transmission. Encoded as shown at H/W NetWork Extended Family.	Uint8	0x11	0x78
H/W NetWork Command Type = 0x0D Extended Family Set New [Downstream]
New H/W NetWork Extended Family payload	Command used to get both the H/W NetWork Family 0-8 and H/W NetWork Sub-Family 1-7 in one single transmission. Encoded as shown at H/W NetWork Extended Family.	Uint8	0x11	0x78

3.10.2. H/W NetWork Command Type¶

H/W NetWork Command Types
Command Type:	Description
0x02	Connection Request
0x03	Family Request [New family if available]
0x04	Family Set
0x05	Join Denied
0x06	Get Family
0x07	Family
0x08	Get SubFamily
0x09	SubFamily
0x0A	SubFamily Set
0x0B	Get Extended Family
0x0C	Extended Family
0x0D	Extended Family Set
0x0E	Reset Long Press Timing

3.10.3. H/W NetWork Family¶

H/W NetWork Families (Colours)
Family:	Colours:	#:
Family 1	Green	0x01
Family 2	Yellow	0x02
Family 3	Red	0x03
Family 4	Blue	0x04
Family 5	Purple	0x05
Family 6	Light Blue	0x06
Family 7	Teal	0x07
Family 8	Pink	0x08
Family 0 (zero)	White^[1]	0x00

^[1] Optional Platform Family

3.10.4. H/W NetWork Sub-Family¶

H/W NetWork Families (Flashes)^[A]
Family:	Flashes:	#:
Sub-Family 1	One Flash	0x01
Sub-Family 2	Two Flashes	0x02
Sub-Family 3	Three Flashes	0x03
Sub-Family 4	Four Flashes	0x04
Sub-Family 5	Five Flashes	0x05
Sub-Family 6	Six Flashes	0x06
Sub-Family 7	Seven Flashes	0x07

^[A] The flashes is “dark periodes” of the normal Family color. E.g. Family 1 and Sub-Family 3 is shown as Green with 3 periods of “NO light”.

3.10.5. H/W NetWork Extended Family¶

The H/W NetWork Extended Family is encoded in one single byte as:

s = SubFamily^[B] f = Family^[B] Bit 7 is reserved for future use

Bit 7 sss ffff

Examples:
`0` `001` `0001`	Family 1, Sub-Family 1
`0` `001` `0010`	Family 2, Sub-Family 1
—	—
—	—
`0` `011` `0101`	Family 5, Sub-Family 3
`0` `111` `1000`	Family 8, Sub-Family 7

^[B] Family 0 (zero) and Sub-Family 0 (zero) NOT used.

3.11. F/W Update - Go Into Boot Mode¶

Message Type - Go Into Boot Mode [0x10]

Communication:

Size:

Description:

Downstream

12 Bytes

This is the FirmWare update message a.k.a. Go Into Boot Mode. Since this a serious command a safety check string is added. The command will trigger a message on the Hub Actions Notification (0x02).

3.11.1. Go Into Boot Mode Message Format¶

Go Into Boot Mode Message Format
Name	Description	Format	Min	Max
Common Header	See Common Message Header	N/A	N/A	N/A
Safety String	Safety String[0] = ‘L’ Safety String[1] = ‘P’ Safety String[2] = ‘F’ Safety String[3] = ‘2’ Safety String[4] = ‘-‘ Safety String[5] = ‘B’ Safety String[6] = ‘o’ Safety String[7] = ‘o’ Safety String[8] = ‘t’	UInt8[9]	N/A	N/A

3.12. F/W Update Lock memory¶

Message Type - F/W Update Lock Memory [0x11]

Communication:

Size:

Description:

Downstream

11 Bytes

This is the safety memory lock used in the production (NOT for the enduser). The FirmWare can still be updated, but only via the application itself - NOT via a debugger tool and alike. The safety string Lock Mem should be applied. The chip resets after this command.

3.12.1. F/W Update Lock Memory Message Format¶

F/W Update Lock Memory Message Format
Name	Description	Format	Min	Max
Common Header	See Common Message Header	N/A	N/A	N/A
Safety String	Safety String[0] = ‘L’ Safety String[1] = ‘o’ Safety String[2] = ‘c’ Safety String[3] = ‘k’ Safety String[4] = ‘-‘ Safety String[5] = ‘M’ Safety String[6] = ‘e’ Safety String[7] = ‘m’	Uint8[8]	N/A	N/A

3.13. F/W Update Lock Status Request¶

Message Type - F/W Update Lock Status Request [0x12]

Communication:

Size:

Description:

Downstream

3 Bytes (NO payload - ONLY Header)

Checking the Memory Locking state at the BOOT-loader memory area. Used in the production (NOT for the enduser). Triggers an answer on F/W Lock Status [0x13]

3.13.1. F/W Update Lock Status Request Message Format¶

F/W Update Lock Status Request Message Format
Name	Description	Format	Min	Max
Common Header	See Common Message Header	N/A	N/A	N/A

3.14. F/W Lock Status¶

Message Type - F/W Update Lock Status [0x13]

Communication:

Size:

Description:

Upstream

4 Bytes

Answer to the F/W Update Lock Status Request [0x12]

3.14.1. F/W Update Lock Status Message Format¶

F/W Update Lock Status Message Format
Name	Description	Format	Min	Max
Common Header	See Common Message Header	N/A	N/A	N/A
Lock Status	Actual Memory Locking Status 0x00 : Lock Status == OK 0xFF : Lock Status == NOT LOCKED	Uint8	0x00	0xFF

3.15. Port Information Request¶

Message Type - Port Information Request [0x21]

Communication:

Size:

Purpose:

Triggers Reply

Downstream

5 Bytes

Request Port Info and Value.

The reply is dependent of the Information Type.

Information Type
0x00 ==> 0x45 Port Value (Standard Ports)
0x00 ==> 0x46 Port Value (Combined Mode Ports)

0x01 ==> 0x43 Port Information (Common For All Ports)
0x02 ==> 0x43 Port Information (Common For All Ports)

3.15.1. Port Information Request Format¶

Port Information Request Message Format
Name	Description	Format	Min	Max
Common Header	See Common Message Header	N/A	N/A	N/A
Port ID	The Port ID associated with the Attached I/O assigned by the Hub	Uint8	0x00	Port ID
Information Type	Identifies the Requested Information Type.	Uint8	0x00	0x02

3.15.2. Information Type¶

Information Type
Information Type	Description
0x00	Port Value
0x01	Mode Info
0x02	Possible Mode Combinations. Should only be used if the “Logical Combinable”-bit is set in the (MODE INFO Capabilities byte). I.e. in the Port Information 0x43

3.16. Port Mode Information Request¶

Message Type - Port Mode Information Request [0x22]

Communication:

Size:

Purpose:

Triggers Reply

Downstream

6 Bytes

Request information about the different modes of the LPF2 Device connected to the port.

Triggers a reply on Port Mode Information [0x44]. The reply is dependent of the requested Mode Information Types.

3.16.1. Port Mode Information Request Format¶

Port Mode Information Request Format
Name	Description	Format	Min	Max
Common Header	See Common Message Header	N/A	N/A	N/A
Port ID	The Port ID associated with the Attached I/O assigned by the Hub	Uint8	0	Port ID
Mode	The Mode to get information for	Uint8	0	N/A
Information Type	Identifies the Mode Information Types	Uint8	0	128

3.16.2. Mode Information Types¶

Mode Information Type
Mode Information No	Info Short Name	Description**
0x00	NAME	Name of the mode
0x01	RAW	The raw range
0x02	PCT	The percent range
0x03	SI	The SI value range
0x04	SYMBOL	The standard name of value
0x05	MAPPING
0x06		Used internally
0x07		Motor Bias (0-100%)
0x08		Capability bits (6 bytes total)
0x80	VALUE FORMAT	Value encoding

3.17. Port Input Format Setup (Single)¶

Message Type - Port Input Format Setup (Single) [0x41]

Communication:

Size:

Purpose:

Triggers Reply:

Downstream

10 Bytes

Setup the mode of operation for the LPF2 Device connected to the addressed Port.

Triggers a reply on Port Input Format [0x47].

3.17.1. Format of Port Input Format Setup (Single)¶

Format of Port Input Format Setup (Single)
Name	Description	Format	Min	Max
Common Header	See Common Message Header	N/A	N/A	N/A
Port ID	The Port ID associated with the Attached I/O assigned by the Hub	Uint8	0	Port ID
Mode	The Mode to get information for	Uint8	0	N/A
Delta Interval	The changes in the delta value to trigger a value update. If set to 0 (zero) data will be send as fast as possible (live data) should NOT be use due to the limited Bluetooth LE bandwidth. Remark: If a sensor is used in combined mode, the Delta Interval should be set for each of the combined modes. E.g. A sensor set to both give discrete color values (0-6) and RAW data, should NOT have the Delta Interval for the RAW data set to ‘1’. The RAW data would trigger a lot of updates and hence flood fill the BLE radio link.	Uint32	0	N/A
Notification Enabled	Enabling notification of value changes. If NOT enabled the input value(s) can only be read by Port Information 0x21 property 000. 0 = Disabled 1 = Enabled	Uint8	0	1

3.18. Port Input Format Setup (CombinedMode)¶

Message Type - Port Input Format Setup (CombinedMode) [0x42]
Communication:	Downstream
Size:	7 Bytes - SubCommand 0x01 5 Bytes - All other SubCommands (I.e. != 0x01)
Purpose:	This command is used to setup a sensor which can be used with more combinations of Mode and DataSets (CombinedMode). I.e. by setting a sensor in Combined Mode, the user can have data of different formats from a sensor in one and only transmission.The count of and the possible combinations are retrieved from the Port Information Request [21] with the sub command 0x02: POSSIBLE MODE COMBINATIONS. If the Combination 0 multi update is enabled, an update (delta interval reached) from the Mode/Dataset[0] will automatically contain a total update of all the Mode/Data-sets setup in the Combined Mode setup session. To setup of a Combined Sensor the user has to follow the following steps: Lock LPF2 Device for setup (allowing multiple setup of modes without actually changing the mode). Setup all the individual modes i.e. more 0x41 setup commands - each setup will result in a individual Port Input Format (Single) (0x47) handshake packet. The setup of the ModeAndDataSet combinations should be done in a prioritized order - if the Combination 0 multi update is wanted, the Mode and Dataset for the very first setup (Mode/Dataset[0]) should be carefully selected. Changes to this dataset will become a sort of a common update all event. The setup order is also the order of the Mode/DataSet bit-pointers used to address the data-values in the Value (CombinedMode) (0x46) First Dataset setup equals Bit-pointer 0 (zero), second Dataset setup equals Bit-pointer 1 etc. UnlockAndStart the LPF2 device with or without the Enable Combination 0 multi update - i.e. subcommand 0x03 or 0x04.
Triggers Reply	Triggers a reply on Port Input Format [0x48].

3.18.1. Format of Port Input Format Setup (CombinedMode)¶

Format of Port Input Format Setup (CombinedMode)

Name

Description

Format

Min

Max

Common Header

See Common Message Header

N/A

Port ID

The unique Port ID for this combined sensor

Uint8

0

Port ID

Sub Command

Port Input Format Setup (Sub-) Commands

Uint8

0

6

Sub Command = 0x01 SetModeDataSet combination(s)

Combination Index

Combination index from the LPF2 device Port Information Request sub command 0x03: POSSIBLE MODE COMBINATIONS [Combination index]. The H/W will use this information to setup the right mode of operation. The Mode/Dataset combinations cannot give this information - the user can choose a subset of the possible Mode/Dataset combinations and hence a given combination is not explicit!

Uint8

0

7

Mode/DataSet[0]

Mode	DataSet
MMMM	DDDD

If the combined sensor is unlocked with the command UnlockAndStartWithMultiUpdate Enabled, the value updates of Mode/DataSet[0] will trigger a total update of all the chosen combinations of the Combined Sensor (Master update).

Uint8

N/A

Mode/DataSet[1]

Mode	DataSet
MMMM	DDDD

Uint8

N/A

Mode/DataSet[n]

Mode	DataSet
MMMM	DDDD

Uint8

N/A

3.18.2. Port Input Format Setup (Sub-) Commands¶

Port Input Format Setup (Sub-) Commands
Sub-Command:	**Description
0x01	Set ModeAndDataSet combination(s)
0x02	Lock LPF2 Device for setup
0x03	UnlockAndStartWithMultiUpdateEnabled
0x04	UnlockAndStartWithMultiUpdateDisabled
0x05	NOT USED
0x06	Reset Sensor ^[X]

^[X] Reset the sensor to the legacy mode 0 (zero)

3.18.3. POSSIBLE MODE COMBINATIONS¶

The possible mode combinations are stored as a one-dimensional array of maximum 8 UInt16. I.e. A list showing a maximum of 8 different combinations each of max. 16 modes.

POSSIBLE MODE COMBINATIONS
Combination Index:	Modes:	Valid Combination Examples
Index 0	0 0 0 0 0 0 0 0 0 0 0 1 0 1 1 0	Mode 1 + Mode 2 + Mode 4
Index 1	0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1	Mode 0 + Mode 1
Index 2	0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1	Mode 0 + Mode 3
Index 3	0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0	“End-of-combinations”
Index 4	0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
Index 5	0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
Index 6	0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
Index 7	0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

3.19. Port Information¶

Message Type - Port Information [0x43]

Communication:

Size:

Purpose:

Replies:

Upstream

Information Type 0x01 : 11 Bytes

Information Type 0x02 : 7 Bytes (1 combination) up to 21 Bytes (8 combinations).

Returns the specified information about the LPF2 Device connected to the Port.

Port Information Request [0x21] (Information Type: 0x01-0x02).

3.19.1. Port Information Format¶

Port Information Format

Name

Description

Format

Min

Max

Common Header

See Common Message Header

N/A

Port ID

The Port ID associated with the Attached I/O assigned by the Hub

Uint8

0

Port ID

Information type

Identifies the Information Type:

0x01	MODE INFO
0x02	POSSIBLE MODE COMBINATIONS

Uint8

0x01

0x02

Information Type == MODE INFO (001)

Capabilities

Bit 4..7	N/A
Bit 3	Logical Synchronizable
Bit 2	Logical Combinable
Bit 1	Input (seen from Hub)
Bit 0	Output (seen from Hub)

Uint8

0x00

0x0F

Total Mode Count

Total number of port modes

Uint8

0

255

Input Modes

Available Input Port Modes (bitmask)

Bit 15	Mode 15
…	…
Bit 0	Mode 0

Uint16

0

65535

Output Modes

Available Output Port Modes (bitmask)

Bit 15	Mode 15
…	…
Bit 0	Mode 0

Uint16

0

65535

Information Type == POSSIBLE MODE COMBINATIONS (002)

Mode Combinations

Up to 8 times UWORD bit-fields showing the possible mode/value-sets combinations for a given sensor. Some combinations cannot be used due to the need for different H/W setup (mode affects each others, H/W switch- and settling time etc.)^[Y]

See also POSSIBLE MODE COMBINATIONS for more information and an example.

Uint8

0

15

^[Y] Mode combinations NOT possible are discarded by the sensor.

3.20. Port Mode Information¶

Message Type - Port Mode Information [0x44]

Communication:

Size:

Purpose:

Replies:

Upstream

Information Type 0x00 : 17 Bytes
Information Type 0x01 : 14 Bytes
Information Type 0x02 : 14 Bytes
Information Type 0x03 : 14 Bytes
Information Type 0x04 : 11 Bytes
Information Type 0x05 :  8 Bytes
Information Type 0x06 : -
Information Type 0x07 :  7 Bytes
Information Type 0x08 : 12 Bytes
-
Information Type 0x80 : 10 Bytes

Returns specified Mode Information Types about the LPF2 device connected to the Port.

Port Mode Information [0x22] (Information Type: 0x00-0x80).

3.20.1. Port Mode Information Format¶

Port Mode Information Format

Name

Description

Format

Min

Max

Common Header

See Common Message Header

N/A

Port ID

The Port ID associated with the Attached I/O assigned by the Hub

Uint8

0

Port ID

Mode

The mode of the Input. Possible values and interpretation depends on the specific Input Type.

Uint8

N/A

Mode Information Types

Identifies the Information Type

Uint8

0

0x80

Information Type == NAME (000)

Name

The maximum length is 11 chars NOT ASCIIZ terminated - length is decoded from total packet length. ONLY ASCII chars: 0x30.. 0x39, 0x41..0x5A, 0x5F and 0x61..0x7A are allowed.

Uint8[0..10]

1

11

Information Type == RAW (001)

RAW Range

The range for the raw (transmitted) signal, remember other ranges are used for scaling the value.

RawMin, RawMax [2 * 4 bytes [FLOATING POINT]]

N/A

Information Type == PCT (002)

PCT Range

What % window should the RAW values be scaled to.
E.g.
If
RAW == 0-200
PCT == 0-100
Then
100 RAW == 50%.

PctMin, PctMax [2 * 4 bytes [FLOATING POINT]]

N/A

Information Type == SI (003)

SI Range

As above

SiMin, SiMax [2 * 4 bytes [FLOATING POINT]]

N/A

Information Type == SYMBOL (004)

Symbol

The standard name for a given output. E.g. DEG for degrees. Normally shortened to max. 5 chars.

Uint8[0..4]

1

5

Information Type == MAPPING (005)

Mapping

xxxx xxxx	INPUT SIDE
Bit 7	Supports NULL value
Bit 6	Supports Functional Mapping 2.0+
Bit 5	N/A
Bit 4	ABS (Absolute [min..max])
Bit 3	REL (Relative [-1..1])
Bit 2	DIS (Discrete [0, 1, 2, 3])
Bit 1	N/A
Bit 0	N/A

yyyy yyyy	OUTPUT SIDE
Bit 7	Supports NULL value
Bit 6	Supports Functional Mapping 2.0+
Bit 5	N/A
Bit 4	ABS (Absolute [min..max])
Bit 3	REL (Relative [-1..1])
Bit 2	DIS (Discrete [0, 1, 2, 3])
Bit 1	N/A
Bit 0	N/A

The roles are: The host of the sensor (even a simple and dumb black box) can then decide, what to do with the sensor without any setup (default mode 0 (zero). Using the LSB first (highest priority).

Uint16 xxxx xxxx yyyy yyyy

N/A

Information Type == MOTOR BIAS (007)

Motor Bias

Initial PWM percentage for a given motor to start running (is of course also depending of use case). 0 - 100 %

Uint8

0

100

Information Type == CAPABILITY BITS (008)

Capability Bits

Sensor capabilities as bits. A total of 48 bits (6 bytes) can be retrieved from a sensor. For decoding see separate doc. Bytes sent as BIG endianness.

Byte 5	Bit 47 (byte 5 bit 7)
	Bit 46 (byte 5 bit 6)


	Bit 40 (byte 5 bit 0)
Byte 4 Byte 3 Byte 2 Byte 1
Byte 0	Bit 7 (byte 0 bit 7)



	Bit 0 (byte 0 bit 0)

Uint8[6]

Information Type == VALUE FORMAT (128)

Value Format

Returns the Value Format. No of datasets, type and number of digits.

Uint8[4]

N/A

3.21. Port Value (Single)¶

Message Type - Port Value (Single) [0x45]

Communication:

Size:

Purpose:

Replies:

Upstream

Only one Port Value in each message:
5 Bytes if Port Value = UInt8
6 Bytes if Port Value = UInt16
8 Bytes if Port Value = UInt32 or FLOAT

Example with more port values in a single message:

Fixed size + Port Count * (1 + value size)

E.g. 3 port values - 2 FLOATs and 1 UInt16:

Header + 2 * (1 + 4) + 1 * (1 + 2) = 16 Bytes

Updates the host with addressed LPF2 Device data. Multiple data in one transmission (from more ports), but only from one Hub, the Hub addressed in the Common header. Size of data and type are interpreted using the Port Format received in the Port Mode Information 0x44.

0x21 Port Value (Information Type: 0x00) (polled mode) Value is updated automatically using the notification if enabled.

3.21.1. Port Value (Single) Format¶

Port Value (Single) Format
Name	Description	Format	Min	Max
Common Header	See Common Message Header	N/A	N/A	N/A
The following repeated for each value in this transmission:
Port ID	The unique Port ID for this sensor	Uint8	0	Port ID
Input Value	The value of the addressed port	Depending of the port format	N/A	N/A

3.21.2. Value Format¶

LPF2 Value Format
Byte[0]	Number of datasets
Byte[1]	Dataset type
	00	8 bit
	01	16 bit
	10	32 bit
	11	FLOAT
Byte[2]	Total figures
Byte[3]	Decimals if any

3.22. Port Value (CombinedMode)¶

Message Type - Port Value (Combined) [0x46]

Communication:

Size:

Purpose:

Replies:

Upstream

6 Bytes + the individual size(s) of all the values.

Updates the host with values from a Combined Mode sensor. I.e. a sensor that can deliver data from different modes in one message.

The updated mode/dataset combination value(s) are addressed by the use of Value bit pointer(s).

There will only be updated data from inputs opened by the notification enabled command.

Updates can be further controlled using the Enable Combination 0 multi update. When using a Combined mode sensor, the user can define individual Delta Interval values for all the combined sensor modes. The first mode/dataset[0] can also be used as a sort of master updater i.e. when the triggerlevel (Delta Interval) for this Mode/Dataset[0] is reached it will automatically update all the other enabled Mode/DataSets in one single message.

0x21 Port Value (Information Type: 0x00) (polled mode) Value is updated automatically using the notification if enabled.

3.22.1. Port Value (Combined) Format¶

Port Value (Combined) Format
Name	Description	Format	Min	Max
Common Header	See Common Message Header	N/A	N/A	N/A
Port ID	The unique Port ID for this sensor	Uint8	0	Port ID
The value pointers are used for addressing the changed value(s). Value size should be decoded using the actual format for the Mode/Dataset.
Mode/Dataset bit pointers	Pointing to the combination of up to 16 mode/data sets. E.g. 0001 0100b means selected mode/datasets 2 and 4. Lowest pointer first (val2, val4). The value size is interpreted by the using the actual Mode/Format setting^[Z] .	Uint16(binary	0	0xFFFF
Input Value change at Mode/Dataset[bit-p]	The changed value of the LPF2-Device at PORT ID. The bit-pointer addresses the next Mode/ dataset changed.	Depends on Input Format.	N/A	N/A
Input Value change at Mode/Dataset[(bit-p) + n]	Changed value of the LPF2-Device at PORT ID. The bit-pointer addresses the first Mode/dataset changed.

^[Z] The user should resolves the data sizes of all the (Value Format) values by using the individual formatting for each mode/dataset combination. These should be initial requested through the Port Mode Information Request (0x22) and received through the Port Mode Information (0x44).

3.23. Port Input Format (Single)¶

Message Type - Port Input Format (Single) [0x47]

Communication:

Size:

Purpose:

Replies To:

Upstream

10 Bytes

Handshake notification of changes made to the Port Input Format.

0x41 Port Input Format Setup (Single)

3.23.1. Format of Port Input Format (Single)¶

Port Input Format (Single) [0x47]
Name	Description	Format	Min	Max
Common Header	See Common Message Header	N/A	N/A	N/A
Port ID	The Port ID associated with the Attached I/O assigned by the Hub	Uint8	0	Port ID
Mode	The mode of the addressed Input.	Uint8	N/A	N/A
Delta Interval	The delta change the Input Value has to change for triggering a new value update notification. Example: a value of 1 means that any change to the value will trigger an update (a form of live data) and a value of 10 means that the value must have changed 10 steps from an earlier notification before triggering a new update i.e. jitter-filtering.	Uint32	0	N/A
Notification ENabled	If notifications are disabled, the Input Value can only be read by sending a read request through the Input Command Characteristic 0 = Disabled 1 = Enabled	Uint8	0	1

3.24. Port Input Format (CombinedMode)¶

Message Type - Port Input Format (CombinedMode) [0x48]

Communication:

Size:

Purpose:

Replies To:

Upstream

7 Bytes

Port Input Format (CombinedMode) is the handshake notification for the setup of one or more bit-pointer in the 16-bit Mode/Dataset Combination Bit Pointer - i.e. bitposition- addressed Mode/DataSet(s). Remember first combination setup referenced through bit 0, second through bit1 etc.

All Format settings will be reset when the input disconnects or the Port is closed.

0x42 Port Input Format Setup (CombinedMode)

3.24.1. Format of Port Input Format (CombinedMode)¶

Format of Port Input Format (CombinedMode)

Name

Description

Format

Min

Max

Common Header

See Common Message Header

N/A

Port ID

The Port ID for this combined sensor

Uint8

0

Port ID

Combined Control Byte

Bit combinations declared below:

Uint8

0

255

Used Cobination Index

Points into the table identifying the possible H/W mode combination(s) of the LPF2 Device being used for this Combined setup. Only bit 0-3 used for this.

0x?0

0x?7

Multi Update

Bit 7 in the Combined Control Byte indicates the actual Multi Update state:

0x1000 ????	Multi Update Enabled
0x0000 ????	Multi Update Disabled

0x0?

0x8?

The Mode/Dataset combination bit pointer is used as acknowledge-handshake for the selected Mode/Dataset combinations (setup went OK). The bits in the bit-pointer follows the address/indexing used in the setup. A bit-pointer setting of 0x0000 means: Notification initiated by a Combined Sensor Mode Clear - i.e. Sub Command ID = Reset Sensor.

Mode/Dataset combination bit pointer

Pointing to the combination of up to 16 mode/ data sets. Thus, a value of e.g. 0000 0000 0001 1111b indicates that the Hub has successfully configured the desired mode/data sets for the value(s) bit-addressed. In the example it means configuring values for 5 mode/datasets.

Uint16(binary

0

0xFFFF

3.25. Virtual Port Setup¶

Message Type - Virtual Port Setup [0x61]

Communication:

Size:

Purpose:

Triggers:

Downstream

If Sub Command = 0x00: 5 Bytes

If Sub Command = 0x01: 6 Bytes

Used to control synchronization of Ports. I.e. connect or disconnect a Virtual Port. It is up to the user (or the HUB) to decide if the virtual connection make sense. E.g. a Motor and a Light output can both be controlled at the same time using e.g. the command StartPower(Power1, Power2).

The Virtual Port gets a new ID while the original Ports keeps the original IDs. All Format settings will be reset when the input disconnects or the Port is closed.

0x04 Hub Attached IO (Only the Virtual Port. The individual are Port IDs kept)

REMARK:

Primo 2018 the running implementations of e.g. synchronized motors in move-bases and HUBs are implemented with implicit Attached IO messages.

I.e. when internal (external) I/O devices can be synchronized (setup as Virtual Port) 3 Attached IO messages is automatically sent: First Port, Second Port and then the Virtual (Third Port).

Current implementation will return an ERROR if this command is sent. This should be changed in upgrades of F/W, so this command just return, what already is implicit set. Will make the interface more consistent for the App developers (same reaction for all calls).Port Input Format Setup (CombinedMode)

3.25.1. Virtual Port Setup Format¶

Virtual Port Setup Format

Name

Description

Format

Min

Max

Common Header

See Common Message Header

N/A

Sub Command

0	Disconnected
1	Connected

Uint8

0

1

If Sub Command == Disconnect (0)

Port ID

The Virtual Port ID to disconnect

Uint8

0

Port ID

If Sub Command == Connect (1)

Port ID A

The Port ID of the first synchronizable Port

Uint8

0

Port ID

Port ID B

The Port ID of the second synchronizable Port

Uint8

0

Port ID

3.26. Port Output Command¶

Message Type - Port Output Command [0x81]

Communication:

Size:

Purpose:

Downstream

The size should be seen as a fixed portion (Common Header, Port ID, Startup and Completion Information, Sub Command token and an variable portion of payload bytes.

Output commands. In the following the commands are group in functional groups.

Motor commands. Single and synchronized ones (simple or drive). Feedback from synchronized.

3.26.1. Port Output Command Format (Common part)¶

Common Message Format for Port Output Command 0x81
Name	Description	Format	Min	Max
Common Header	See Common Message Header	N/A	N/A	N/A
Port ID	The Port ID associated with the Attached I/O assigned by the Hub	Uint8	0	Port ID
Startup and Completion Information	Startup (s) and Completion (c): `ssss` `cccc`	Uint8	0	255
Sub Command	The Sub Command to execute. See further description in the following pages	Uint8	0x00	0xFF
Payload	Payload size (n) depends on the sub-command. The payload is the parameters for the sub-command.	Uint8 * n	0	255

3.26.2. Startup and Completion Information¶

Startup and Completion Information
ssss:	cccc:	Description:
0000	xxxx	Buffer if necessary
0001	xxxx	Execute immediately
0010	xxxx
—
xxxx	0000	No action
xxxx	0001	Command feedback (Status)
xxxx	0010
xxxx	0011
—

3.27. Output Command 0x81 - Motor Sub Commands [0x01-0x3F]¶

3.27.1. Output Sub Command - StartPower(Power)¶

StartPower (Power): Output Command 0x81 - Sub Command N/A

Sub Command Value Parameter Description Description

StartPower (Power)

N/A

Power [Int8]:

[-100..-1]	CCW PWM 1-100%
[1..100]	CW PWM dutycycle 1-100%
[0]	FLOAT
[127]	BRAKE

Single: Turn on/off motor unregulated.

Synchronized: Turn on/off both motors

Encoded through WriteDirectModeData

3.27.2. Output Sub Command - StartPower(Power1, Power2) [0x02]¶

StartPower (Power1, Power2): Output Command 0x81 - Sub Command 0x02

Sub Command Value Parameter Description Description

StartPower (Power1, Power2)

0x02

Power1, Power2 [Int8, Int8]:

[-100..-1]	CCW PWM 1-100%
[1..100]	CW PWM dutycycle 1-100%
[0]	FLOAT
[127]	BRAKE

Single: N/A

Synchronized: Turn on/off BOTH motors unregulated.

Encoded through WriteDirectModeData

3.27.3. Output Sub Command - SetAccTime (Time, ProfileNo) [0x05]¶

SetAccTime (Time, ProfileNo) : Output Command 0x81 - Sub Command 0x05

Sub Command

Value

Parameter Description

Description

SetAccTime (Time, ProfileNo)

0x05

Time [Int16]:

[0..10000]ms (Upper limit - normally used with less)

ProfileNo [Int8]:

[0..MAX_PROFILES]

The selected profile will be used in all motor based commands if the UseProfileFlag is set TRUE. The Time and Profile Number set for the profile is ignored if the UseProfile-Flag is set FALSE.

Single/Synchronized:

Sets an acceleration profile for the motor(s)

The Time is the duration time for an acceleration from 0 to 100%. I.e. a Time set to 1000 ms. should give an acceleration time of 300 ms. from 40% to 70%

3.27.4. Output Sub Command - SetDecTime (Time, ProfileNo) [0x06]¶

SetDecTime (Time, ProfileNo) : Output Command 0x81 - Sub Command 0x06

Sub Command

Value

Parameter Description

Description

SetDecTime (Time, ProfileNo)

0x06

Time [Int16]:

[0..10000]ms (Upper limit - normally used with less)

ProfileNo [Int8]: [0..MAX_PROFILES]

The selected profile will be used in all motor based commands if the UseProfileFlag is set TRUE. The Time and Profile Number set for the profile is ignored if the UseProfile-Flag is set FALSE.

Single/Synchronized:

Sets a deceleration profile for the motor(s)

The Time is the duration time for an deceleration from 100% to 0. I.e. a Time set to 1000 ms. should give an deceleration time of 400 ms. from 80% down to 40%

3.27.5. Output Sub Command - StartSpeed (Speed, MaxPower, UseProfile) [0x07]¶

StartSpeed (Speed, MaxPower, UseProfile) : Output Command 0x81 - Sub Command 0x07

Sub Command

Value

Parameter Description

Description

StartSpeed (Speed, MaxPower, UseProfile)

0x07

Speed [Int8]:

[-100..-1]	CCW PWM 1-100%
[1..100]	CW PWM 1-100%
[0]	implicite [126] HOLD POSITION

If FLOAT or BRAKE should be used e.g. when a slider is set to 0 (zero) the user has to use either StartPower(0 or 127).

MaxPower [Int8]:

[ABS(0..100)]%

UseProfile [Int8]:

[0 = DO NOT USE, 1 = USE PROFILE]

0x0000000?	Acc.- profile
0x000000?0	Decc.- profile

Single/Synchronized:

START or HOLD the motor(s) and keeping the SPEED/POSITION NOT using power-levels greater than MaxPower.

3.27.6. Output Sub Command - StartSpeed (Speed1, Speed2, MaxPower, UseProfile) [0x08]¶

StartSpeed (Speed1, Speed2, MaxPower, UseProfile) : Output Command 0x81 - Sub Command 0x08

Sub Command

Value

Parameter Description

Description

StartSpeed (Speed1, Speed2, MaxPower, UseProfile)

0x08

Speed1, Speed2 [Int8]:

[-100..-1]	CCW PWM dutycycle 1-100%
[1..100]	CW PWM dutycycle 1-100%
[0]	implicite [126] HOLD POSITION

If FLOAT or BRAKE should be used e.g. when a slider is set to 0 (zero) the user has to use either StartPower(0 or 127).

MaxPower [Int8]:

[ABS(0..100)]%

UseProfile [Int8]:

[0 = DO NOT USE, 1 = USE PROFILE]

0x0000000?	Acc.- profile
0x000000?0	Decc.- profile

Single:

N/A

Synchronized:

START or HOLD the motor(s) and keeping the SPEED/POSITION NOT using power-levels greater than MaxPower.

3.27.7. Output Sub Command - StartSpeedForTime (Time, Speed, MaxPower, EndState, UseProfile) [0x09]¶

StartSpeedForTime (Time, Speed, MaxPower, EndState, UseProfile) : Output Command 0x81 - Sub Command 0x09

Sub Command

Value

Parameter Description

Description

StartSpeedForTime (Time, Speed, MaxPower, EndState, UseProfile)

0x09

Time [Int16]:

[0..MAX_INT16]ms

Speed [Int8]:

[-100..100]%

MaxPower [Int8]:

[ABS(0..100)]%

EndState[Int8]:

[0 = FLOAT, 126 = HOLD, 127 = BRAKE]

[0 = DO NOT USE, 1 = USE PROFILE]

0x0000000?	Acc.- profile
0x000000?0	Decc.- profile

Single/Synchronized:

Start the motor(s) for Time ms. keeping a speed of Speed using a maximum power of MaxPower. After Time stopping the output using the EndState.

3.27.8. Output Sub Command - StartSpeedForTime (Time, Speed, MaxPower, EndState, UseProfile) [0x0A]¶

StartSpeed (Time, SpeedL, SpeedR, MaxPower, EndState, UseProfile) : Output Command 0x81 - Sub Command 0x0A

Sub Command

Value

Parameter Description

Description

StartSpeedForTime(Time, SpeedL, SpeedR, MaxPower, EndState, UseProfile)

0x0A

Time [Int16]:

[0.. MAX_INT16]ms

SpeedL, SpeedR [Int8]:

[-100..100]%

MaxPower [Int8]:

[ABS(0..100)]%

EndState[Int8]:

[0 = FLOAT, 126 = HOLD, 127 = BRAKE]

[0 = DO NOT USE, 1 = USE PROFILE]

0x0000000?	Acc.- profile
0x000000?0	Decc.- profile

Single:

N/A

Synchronized:

Start the motors for Time ms. And try to keep individual speeds using Speed(X) while using a maximum power of MaxPower. After Time stopping the outputs using the EndState.

3.27.9. Output Sub Command - StartSpeedForDegrees(Degrees, Speed, MaxPower, EndState, UseProfile) [0x0B]¶

StartSpeedForDegrees(Degrees, Speed, MaxPower, EndState, UseProfile) : Output Command 0x81 - Sub Command 0x0B

Sub Command

Value

Parameter Description

Description

StartSpeedForDegrees(Degrees, Speed, MaxPower, EndState, UseProfile)

0x0B

Degrees [Int32]:

[1..MAX_INT32]

Speed [Int8]:

[-100..100]%

MaxPower [Int8]:

[ABS(0..100)]%

EndState[Int8]:

[0 = FLOAT, 126 = HOLD, 127 = BRAKE]

[0 = DO NOT USE, 1 = USE PROFILE]

0x0000000?	Acc.- profile
0x000000?0	Decc.- profile

Single/Synchronized:

Start the motor(s) for Degrees at a speed of Speed using a maximum power of MaxPower. After Degrees stopping the output using the EndState. Direction controlled solely by the sign of the Speed param.

3.27.10. Output Sub Command - StartSpeedForDegrees(Degrees, SpeedL, SpeedR, MaxPower, EndState, UseProfile) [0x0C]¶

StartSpeedForDegrees(Degrees, SpeedL, SpeedR, MaxPower, EndState, UseProfile) : Output Command 0x81 - Sub Command 0x0C

Sub Command

Value

Parameter Description

Description

StartSpeedForDegrees(Degrees, SpeedL, SpeedR, MaxPower, EndState, UseProfile)

0x0C

Degrees [Int32]:

[0..10000000]

(NO signed value - See Tacho Math)

SpeedL, SpeedR [Int8]:

[-100..100]%

MaxPower [Int8]:

[ABS(0..100)]%

EndState[Int8]:

[0 = FLOAT, 126 = HOLD, 127 = BRAKE]

[0 = DO NOT USE, 1 = USE PROFILE]

0x0000000?	Acc.- profile
0x000000?0	Decc.- profile

Single:

N/A

Synchronized:

Start the motors for Degrees and try to keep individual speeds using Speed(X) while using a maximum power of MaxPower. After Degrees is reached stop the outputs using the EndState.

3.27.11. Output Sub Command - GotoAbsolutePosition(AbsPos, Speed, MaxPower, EndState, UseProfile) [0x0D]¶

GotoAbsolutePosition(AbsPos, Speed, MaxPower, EndState, UseProfile) : Output Command 0x81 - Sub Command 0x0D

Sub Command

Value

Parameter Description

Description

GotoAbsolutePosition(AbsPos, Speed, MaxPower, EndState, UseProfile)

0x0D

AbsPos [Int32]:

[MIN_INT32..MAX_INT32]

Speed [Int8]:

[1..100]%

MaxPower [Int8]:

[ABS(0..100)]%

EndState[Int8]:

[0 = FLOAT, 126 = HOLD, 127 = BRAKE]

[0 = DO NOT USE, 1 = USE PROFILE]

0x0000000?	Acc.- profile
0x000000?0	Decc.- profile

Single:

Start the motor with a speed of Speed using a maximum power of MaxPower and GOTO the Absolute position AbsPos. After position is reached the motor is stopped using the EndState mode of operation.

Synchronized: As above - but using the Virtual Port as destination for the command.

3.27.12. Output Sub Command - GotoAbsolutePosition(AbsPos1, AbsPos2, Speed, MaxPower, EndState, UseProfile) [0x0E]¶

GotoAbsolutePosition(AbsPos1, AbsPos2, Speed, MaxPower, EndState, UseProfile) : Output Command 0x81 - Sub Command 0x0E

Sub Command

Value

Parameter Description

Description

GotoAbsolutePosition(AbsPos1, AbsPos2, Speed, MaxPower, EndState, UseProfile)

0x0E

AbsPos1, AbsPos2 [Int32]:

[MIN_INT32..MAX_INT32]

Speed [Int8]:

[1..100]%

MaxPower [Int8]:

[ABS(0..100)]%

EndState[Int8]:

[0 = FLOAT, 126 = HOLD, 127 = BRAKE]

[0 = DO NOT USE, 1 = USE PROFILE]

0x0000000?	Acc.- profile
0x000000?0	Decc.- profile

Single:

N/A

Synchronized:

Start the motors with individual speeds calculated from the common given Speed using a powerlevel limited to the MaxPower value. And the GOTO the Absolute positions: AbsPos1 and AbsPos2.

E.g. If the distance to the AbsPosx of one of the motors is 1/3 of the other - the power used also has to be less.

3.27.13. Output Sub Command - PresetEncoder(Position) N/A¶

PresetEncoder(Position) : Output Command 0x81 - Sub Command N/A

Sub Command Value Parameter Description Description

PresetEncoder(Position)

N/A

Position [Int32]:

[MIN_INT32..MAX_INT32]

As a new command (NOT QUEUED) will stop an executing command, the PresetEncoder() will automatically STOP the Motor(s).

Single:

Preset the encoder of the motor to Position.

A 0 (zero) value equals RESET.

Synchronized:

Presets all the encoders: the virtual encoder and both the individual encoders. They are all set to POSITION.

A value of 0 (zero) equals RESET.

Encoded through WriteDirectModeData

3.27.14. Output Sub Command - PresetEncoder(LeftPosition, RightPosition) [0x14]¶

PresetEncoder(LeftPosition, RightPosition) : Output Command 0x81 - Sub Command 0x14

Sub Command

Value

Parameter Description

Description

PresetEncoder(LeftPosition, RightPosition)

0x14

LeftPosition, RightPosition [Int32]:

[MIN_INT32..MAX_INT32]

As a new command (NOT QUEUED) will stop an executing command, the PresetEncoder() will automatically STOP the Motor(s).

Single:

N/A

Synchronized:

Presets ONLY the individual encoders of the synchronized motors to (L/R) Position. The synchronized virtual encoder is NOT affected! A value of 0 (zero) equals RESET.

3.27.15. Output Sub Command - TiltImpactPreset(PresetValue) N/A¶

TiltImpactPreset(PresetValue) : Output Command 0x81 - Sub Command N/A

Sub Command Value Parameter Description Description

TiltImpactPreset(PresetValue)

N/A

PresetValue: [Int32]

PresetValue [0..MAX_INT32]

(P)Resets the Mode 3 ImpactCounts.

Encoded through WriteDirectModeData

3.27.16. Output Sub Command - TiltConfigOrientation(Orientation) N/A¶

TiltConfigOrientation(Orientation) : Output Command 0x81 - Sub Command N/A

Sub Command Value Parameter Description Description

TiltConfigOrientation(Orientation)

N/A

Orientation: [Int8]

Orientation [0-6]:

0	Bottom (Default/Normal)
1	Front
2	Back
3	Left
4	Right
5	Top
6	Use actual as Bottom reference.

Set the default bottom side (orientation) mode 5.

Encoded through WriteDirectModeData

If 6 “Use actual as Bottom reference” is issued, then all other orientations are relative to this.

3.27.17. Output Sub Command - TiltConfigImpact(ImpactThreshold, BumpHoldoff) N/A¶

TiltConfigImpact(ImpactThreshold, BumpHoldoff) : Output Command 0x81 - Sub Command N/A

Sub Command Value Parameter Description Description

TiltConfigImpact(ImpactThreshold, BumpHoldoff)

N/A

ImpactThreshold: [Int8] ImpactThreshold [0-127]

BumpHoldoff: [Int8] [1..127] 10th of ms

Sets the Impact size for a BUMP - mode 6.

Sets the minimum Holdoff time between individual impacts (Bumps).

The HoldOff can be set between 10 ms. and 1.27 second.

Encoded through WriteDirectModeData

3.27.18. Output Sub Command - TiltFactoryCalibration(Orientation, PassCode) N/A¶

TiltFactoryCalibration(Orientation, PassCode) : Output Command 0x81 - Sub Command N/A

Sub Command Value Parameter Description Description

TiltFactoryCalibration(Orientation, PassCode)

N/A

Orientation: [Int8]

1	XY
2	Z

PassCode = Calib-Sensor

Tells the orientation set physically by the montage automat - Mode 7.

XY	Laying flat
Z	Standing (long dir.)

Encoded through WriteDirect

3.27.19. Output Sub Command - HARDWARE RESET GenericZeroSetHardware() N/A¶

HARDWARE RESET : Output Command 0x81 - Sub Command N/A
Sub Command	Value	Parameter Description	Description
GenericZeroSetHardware()	N/A	Resets or zerosets the H/W component attached to the Port ID	Transmits the universal H/W Reset 0x11 token to the addressed H/W. `Encoded through` WriteDirect

3.27.20. Output Sub Command - SetRgbColorNo(ColorNo) N/A¶

SetRgbColorNo(ColorNo) : Output Command 0x81 - Sub Command N/A

Sub Command Value Parameter Description Description

SetRgbColorNo(ColorNo)

N/A

ColorNo: [Int8] [0..10]

Show the Color specified by ColorNo.

Encoded through WriteDirectModeData

3.27.21. Output Sub Command - SetRgbColorNo(RedColor, GreenColor, BlueColor) N/A¶

SetRgbColorNo(RedColor, GreenColor, BlueColor) : Output Command 0x81 - Sub Command N/A

Sub Command Value Parameter Description Description

SetRgbColors(RedColor, GreenColor, BlueColor)

N/A

RedColor, GreenColor, BlueColor: [UInt8] [0..255, 0..255, 0..255]

Show a color mixed off the individual RGB values.

Encoded through WriteDirectModeData

3.28. WriteDirect¶

3.28.1. Output Sub Command - WriteDirect(Byte[0],Byte[0 + n]) Sub Command [0x50]¶

WriteDirect(Byte[0],Byte[0 + n]) : Output Command 0x81 - Sub Command 0x50

Sub Command

Value

Parameter Description

Description

WriteDirect(Byte[0],Byte[0 + n])

0x50

Byte(x): [Uint8] [0..255]

The user has to add some decorations:

PayLoad[0], PayLoad[1], CheckSum

See Checksum Calculation:

Direct byte values written directly via the H/W-wired to the LPF2 Device at I/O at Port ID.

3.29. WriteDirectModeData¶

3.29.1. Output Sub Command - WriteDirectModeData() Sub Command [0x5]¶

WriteDirectModeData((Mode, PayLoad[0] PayLoad [0 + n]) : Output Command 0x81 - Sub Command 0x51

Sub Command

Value

Parameter Description

Description

WriteDirectModeData(Mode, PayLoad[0] PayLoad [0 + n]

0x51

Mode: [Uint8] [0..MaxMode] Sets the mode.

PayLoad[x]: [Uint8] [0..255] Payload transferred directly to the io-module and used in the previous setup mode.

Commands encoded using this encoding are show in the Appendix: Encoding of WriteDirectModeData [0x81, 0x51]

Write Direct data to a specific mode. I.e. the command will select/ change mode and uses the following payload as para-meters for this new mode.

3.30. Checksum Calculation¶

The Checksum is calculated as:

ChkSum = PayLoad[0] ^ … PayLoad[n] ^ 0xFF

3.31. Tacho Math¶

The Syncronized movement is the average of the two tachocounters with the signed ratio given from the SpeedL and SpeedR. The degrees count limited to 10000000 due to max resolution without internal mathematically overflow.

As an example:

Example A:

Run for 88 Degrees
Left Speed (SpeedL) set to 75
Left Speed (SpeedR) set to 35

The individual tachocounters should travel:

TachoL = ((88 * 2) * 75 * sign(SpeedL)) / (75 + 35) = 120

TachoR = ((88 * 2) * 35 * sign(SpeedR)) / (75 + 35) = 56

Example B:

Run for 160 Degrees
Left Speed (SpeedL) set to 55
Right Speed (SpeedR) set to -48

The individual tachocounters should travel:

TachoL = ((160 * 2) * 55 * sign(SpeedL)) / (55 + |-48|) = 171

TachoR = ((160 * 2) * |-48| * sign(SpeedR)) / (55 + |-48|) = -149

3.32. Port Output Command Feedback¶

Message Type - Port Output Command Feedback [0x82]

Communication:

Size:

Purpose:

Replies To

Upstream

Normally with feedback from 1 (one) port the message size is 5 Bytes. If feedback from more ports, the message size is increased 2 bytes for each additional port.

Allows users to keep track of one or more buffering 1-bytes queue and the progress of requested Port Output Command(s) (0x81). Immediate commands discarding the executing and/or the buffered command(s) are also flagged.

0x81 Port Output Command progress and buffering status

3.32.1. Port Output Command Feedback Format¶

Port Output Command Feedback Message Format [0x81]

Name

Description

Format

Min

Max

Common Header

See Common Message Header

N/A

Port ID

The Port ID for the feedback message

UInt8

0

255

Port FeedBack Message

FeedBack Message (as BIT-fields)

0x01	Buffer Empty + Command In Progress
0x02	Buffer Empty + Command Completed
0x04	Current Command(s) Discarded
0x08	Idle
0x10	Busy/Full

See the Buffering State Machine for further explanation of the Buffering for both the HUB- and SDK side.

Also have a look at the Transmission Flow Control (Preliminary PROPOSAL!).

UInt8

0

0x1F

2nd Port ID

Optional 2nd PortID for the feedback message

UInt8

0

255

Port 2 FeedBack Message

FeedBack Message (as BIT-fields) See above for bit encoding

UInt8

0

0x1F

3rd Port ID

Optional 3rd PortID for the feedback message

UInt8

0

255

Port 3 FeedBack Message

FeedBack Message (as BIT-fields) See above for bit encoding

UInt8

0

0x1F

4. Buffering State Machine¶

Each port can have a command in progress and also a buffered command.

Per port, the state machine for this is as follows:

There are three states:
1. Nothing in progress, buffer empty. (“Idle”)
2. Command in progress, buffer empty (“Busy/Empty”)
3. Command in progress, buffer full (“Busy/Full”)

There are external events which affect the state machine:
1. A command is submitted for immediate execution (“EI”)
2. A command is submitted for execution or buffering - “buffer if necessary” (“Q”)
3. The current command completes (“Done”)
4. An internal FW event occurs which interrupts all pending commands (internal interrupt, “Interrupt”) (Example of this: a virtual motor is interrupted by use of one of its component motors, or vice versa.)
The state machine emits signals in the form of “Port Output Command Feedback” messages to the SDK. (The content of this command could be targetted towards tracking the fates of individual commands, or tracking the buffer state as a whole. We have chosen in the following to go with the latter option.)

Relevant info is:

What the new state is
Whether the state was reached because all existing commands were discarded.
Whether any command was completed successfully (only strictly necessary if we have instantaneous commands; see below).

4.1. State machine specification¶

Old state	Event	–>	New state	Signal out
Idle	Command for EI	–>	Busy/Empty	Busy/Empty
	Command for EI	(–> [&]_)	(Idle)	(Idle + completed)
	Command for Q	–>	Busy/Empty	Busy/Empty
	Command for Q	(–> [&]_)	(Idle)	(Idle + completed)
	Done	–>	N/A	N/A
	Interrupy	–>	N/A	N/A
Busy/Empty	Command for EI	–>	Busy/Empty	Busy/Empty + discarded
	Command for EI	(–> [&]_)	(Idle)	(Idle + discarded + completed)
	Command for Q	–>	Busy/Full	Busy/Full
	Done	–>	Idle	Idle + comleted
	Interrupy	–>	Idle	Idle + discarded
Busy/Full	Command for EI	–>	Busy/Empty	Busy/Empty + discarded
		(–> [&]_)	(Idle)	(Idle + discarded + completed)
	Command for Q		N/A	N/A [&]_
	Done	(–> [&]_)	Busy/Empty	Busy/Empty + completed
	Done	–>	(Idle)	(Idle + completed)
	Interrupy	–>	Idle	Idle + discarded

The rows marked with parentheses is for if we decide to have “instantaneous” commands; there may be FW implementation reasons for doing this. TBD

4.2. SDK-side state machine¶

Given that the FW-side state machine behaves as described above (and that all output commands for a given port are sent with the “feedback desired” bit set), a corresponding SDK-side state machine can be constructed for tracking the buffer state and the fates of all sent commands:

Old state	Feedback event	–>	New state	Conclusions
Idle	Idle + completed	(–>)	Idle	1 command completed
Idle	Busy/Empty	–>	Busy/Empty	(no change)
Busy/Empty	Idle + completed	–>	Idle	1 command completed
	Idle + discarded	–>	Idle	1 command discarded
	Idle + discarded + completed	(–>)	Idle	1 command discarded; to-buffer command completed
	Busy/Empty + discarded	–>	Busy/Empty	1 command discarded
Busy/Full	Idle + completed	(–>)	Idle	2 commands completed
	Idle + discarded	–>	Idle	2 commands discarded
	Idle + discarded + completed	–>	Idle	2 commands discarded; to-buffer command completed
	Busy/Empty + completed	–>	Busy/Empty	1 command discarded
	Busy/Empty + discarded	–>	Busy/Empty	2 commands discarded

5. LEGO Bluetooth Hub Boot Loader Service¶

5.1. LEGO Hub Boot Loader Service¶

The LEGO Bluetooth 3.X Hub Boot Loader Service contains the following service:

Service	UUID
LEGO Hub Boot Loader Service	00001625-1212-EFDE-1623-785FEABCD123

5.1.1. LEGO Hub Boot Loader Characteristic¶

Due to potential future limitations in future BLE chipsets, the LEGO Bluetooth 3.X Hub Boot Loader Service only contains one single characteristic:

Characteristic	UUID
LEGO Hub Boot Loader Characteristic	00001626-1212-EFDE-1623-785FEABCD123

The <1626> LEGO Hub Boot Loader Characteristic Supported Properties
Name	Description
Write with (without??) response	Allows the user app to update the functional F/W of the HUB - NOT the Radio Stack F/W.
Notify	Allows the server to use the Handle Value Notification ATT operation on this characteristic.

5.1.2. The LEGO Hub Boot Loader Advertising Packet¶

Manufacturer Data in the Boot Loader Advertising packet
Name	Description	Format	Min	Max
Length	Length of data	Unit8	0x09	0x09
Data Type	Manufacturer specific data to follow (0xFF)	Uint8	0xFF	0xFF
Manufacturer ID	Manufacturer identifier (LEGO System A/S = 0x0397)	Uint16	0x0397	0x0397
Flash Loader Version	The Loader version is encoded as Version Number Encoding.	Sint32	0	SINT32_MAX
System Type and Device Number	Identifies the system type of the Hub	Uint8	0x00	0xFF
Hub Kind	Identifies the kind of Hub - see Device Capabilities (Hub Kind) for more information.	Uint8	0x01	0xFF

5.2. Flash Loader Functions [0x01]¶

Message Type - Flash Loader Functions [0x01]
Communication:	Downstream + Upstream. Upstream uses notifications. Notifications on as DEFAULT.
Size:	Sub Command	Cmd Token	Downstream	Upstream
	Erase Flash	0x11	1	2
	Program Flash	0x22	5 + bytes to program
	Start APP	0x33	4	N/A
	Initiate Loader	0x44	8	5
	Get Info	0x55	4	17
	Get Checksum	0x66	4	5
	Get FLASH State	0x77	4	5
	Disconnect Device	0x88	4
Description:	Erase Flash	The Flash Loader normally should start erase the FLASH. This command needs NO further parameters - the H/W size etc. are known by the Flash Loader F/W.
	Program Flash	Programs n-bytes [Uint8] at address 0xaaaa aaaa [Uint32].
	Start APP	As it says :-)
	Initiate Loader	Telling the Flash Loader F/W, how many bytes in image. Implicite the command also clears the CheckSum.
	Get Info	By using Get Info, the user can decide Total Length of Flash, Flash Loader F/W version and the H/W Reference ID.
	Get Checksum	Returns the CheckSum - also on the fly.
	Get FLASH State	Get the Protection Level of the FLASH.
	Disconnect Device	Command used for disconnection the device. When disconnected, the device starts advertising. If NO (re-)connection done before end of the advertising period, the device will shut down.

5.2.1. Flash Loader Functions Message Format¶

Flash Loader Functions Message Format

Name

Description

Format

Min

Max

Sub Commands

0x11	Erase Flash
0x22	Program Flash
0x33	Start APP
0x44	Initiate Loader
0x55	Get Info
0x66	Get CheckSum
0x77	Get FLASH State
0x88	Disconnect Device

UInt8

0x11

0x88

Return type and size If Sub Command == 0x11 “Erase Flash”

Return value

Cmd OK - FLASH erased:	0x00
Error:	0xFF

UInt8

0x00

0xFF

Return type and size If Sub Command == 0x22 “Program Flash”

Returned values

CheckSum:

ByteCounts:

Uint8

Uint32

N/A

0x01

N/A

Return type and size If Sub Command == 0x33 “Start App”

Return value

NO RETURN VALUE - booting

Return type and size If Sub Command == 0x44 “Initiate Loader”

Return value

Cmd OK - Init Success	0x00
Error - Byte count out of range:	0xFF

Checksum implicit reset.

Uint8

0x00

0xFF

Return type and size If Sub Command == 0x55 “Get Info”

Return value

Flash Loader Version: Version Number Encoding

SInt32

N/A

Flash Start Address (LSB):

UInt32

N/A

Flash End Address (MSB):

UInt32

N/A

The System Type ID for this H/W:

UInt8

N/A

Return type and size If Sub Command == 0x66 “Get CheckSum”

Return value

Checksum:

See Checksum Calculation

UInt8

N/A

Return type and size If Sub Command == 0x77 “Get FLASH State”

Return value

FLASH State Protection Level:

00	No Protection
01	Level 1 protection
02	Level 2 protection

Uint8

N/A

5.3. Flash Loader Error Messages [0x05]¶

Message Type - Flash Loader Error Messages [0x05]
Communication:	Upstream.
Size:	5 Bytes
Description:	Generic Flash Loader Error message. Error type and number - see below. Errors includes the command ID which introduces the error.

5.3.1. Flash Loader Error Message Format¶

Flash Loader Error Message Format
Name	Description	Format	Min	Max
Common Header	See Common Message Header	N/A	N/A	N/A
Message Type	Command (Message Type) see the definitions in this document.	Uint8	0x01	0xFF
Error Type	0x05 = Command NOT recognized (The ONLY Error type implemented in FLASH Loader)	Uint8	0x05	0x05

6. Appendix¶

6.1. Encoding of WriteDirectModeData [0x81, 0x51]¶

Commands needed for a certain mode setup are encoded using the Output Command 0x81 Sub Command 0x51 “WriteDirectModeData”.

These commands are shown and encoded as shown in the example below:

Output Command 0x81 - TILT Sub Command

Sub Command

Value

Parameter Description

Description

TiltImpactPreset(PresetValue)

N/A

PresetValue: [Int32] PresetValue [0..MAX_INT32]

(P)Resets the Mode 3 ImpactCounts.

Encoded through WriteDirectModeData

TiltConfigOrientation(Orientation)

N/A

Orientation: [Int8] Orientation [0-6]

0	Bottom (Default/Normal)
1	Front
2	Back
3	Left
4	Right
5	Top
6	Use actual as “Bottom reference”

Set the default bottom side (orientation) - mode 5.

Encoded through WriteDirectModeData

TiltConfigImpact(ImpactThreshold , BumpHoldoff)

N/A

ImpactThreshold: [Int8] ImpactThreshold [0-127]

BumpHoldoff: [Int8] 1..127] 10th of ms

Sets the Impact size for a BUMP - mode 6.

Sets the minimum Holdoff time between individual impacts (Bumps).

The HoldOff can be set between 10 ms. and 1.27 Sec.

Encoded through WriteDirectModeData

The prolog part of the command decoration is:

Common Header (See description at Common Message Header).
Startup and Completion information (See description at Startup and Completion Information)
WriteDirectModeData (0x51)
Mode
The rest of the message is the Mode specific payload.

E.g.

Set RGB LED into RGB mode (0x01) and set the R = 0x30, G = 0x47, B = 0x55:

Port ID, Startup and Completion Information , 0x51, 0x01, 0x30, 0x47, 0x55

(P)RESET ENCODER Command encoded as WriteDirectModeData (Cmd 0x81, Sub Cmd 0x51)

WriteModeData Commands

Encoding

Description

PresetEncoder(Value)

Mode 2

Port ID, Startup and Completion Information, 0x51, 0x02, val0, val1, val2, val3

REMEMBER: val0-val3 parts of int 32

Write direct to Position property in sensor. I.e. a value of 0 (zero) equals reset.

MOTOR/OUTPUT Commands encoded as WriteDirectModeData (Cmd 0x81, Sub Cmd 0x51)

WriteModeData Commands

Encoding

Description

StartPower (Power)

Mode 0

Port ID, Startup and Completion Information, 0x51, 0x00, Power

Set port into adjustable PWM output using the param Power. No Speed regulation applied.

RGB Commands encoded as WriteDirectModeData (Cmd 0x81, Sub Cmd 0x51)

WriteModeData Commands

Encoding

Description

SetRgbColorNo(ColorNo)

Mode 0

Port ID, Startup and Completion Information, 0x51, 0x00, ColorNo

Set the RGB LED to ColorNo or presets the ColorNo for later mode (0x00).

SetRgbColors(RedColor, GreenColor, BlueColor)

Mode 0

Port ID, Startup and Completion Information, 0x51, 0x00, 0x51, 0x01, R, G, B

Set the RGB LED to Colors for instant Colors (if RGB already in mode 1) ^[M] .

^[M] Remark! Some sensors can be preset in a mode different from the actual used but this behavior depends of the sensors, the modes and the internal properties. E.g. the RGB uses RGB settings in mode 1, but also uses the internal properties in making the numbered colors in mode 0. If e.g. a RGB sensor is in mode 0 and color 5 show, and a WriteDirectModeData is used to set RGB values to 00,33,00 (direct to mode 1). Then a later switching to mode 1 will NOT set the 00,33,00, but show a turned off RGB. Remember the internal properties is used in both modes. Some sensor can be preset/reset in mode different from actual, but the user has to check the information and behavior for the specific sensor.

TILT Commands encoded as WriteDirectModeData (Cmd 0x81, Sub Cmd 0x51)

WriteModeData Commands

Encoding

Description

TiltImpactPreset(PresetValue)

Mode 3

Port ID, Startup and Completion Information, 0x51, 0x03, PresetValue

Set the Tilt into TiltImpactCount mode (0x03) and change (preset) the value to PresetValue.

SetRgbColors(RedColor, GreenColor, BlueColor)

Mode 5

Port ID, Startup and Completion Information, 0x51, 0x05, Orientation

Set the Tilt into TiltOrientation mode (0x05) and set the Orientation value to Orientation

TiltConfigImpact(ImpactThreshold, BumpHoldOff)

Mode 6

Port ID, Startup and Completion Information, 0x51, 0x06, ImpactThreshold, BumpHoldoff

Setup Tilt ImpactThreshold and BumpHoldoff by entering mode 6 and use the payload ImpactThreshold and BumpHoldoff.

TiltFactoryCalibration(Orientation, CalibrationPassCode)

Mode 7

Port ID, Startup and Completion Information, 0x51, 0x07, Orientation, ‘C’, ‘a’, ‘l’, ‘i’, ‘b’, ‘-‘, ‘S’, ‘e’, ‘n’, ‘s’, ‘o’, ‘r’,

Sets the actual orientation in the montage automat.

0	XY (laying flat)
1	Z Standing (long direction)
PassCode	“Calib Sensor”

6.2. Encoding of WriteDirect [0x81, 0x50]¶

To gain direct access to H/W components the user can use the WriteDirect Command. The command is a sort of feed through. So for sending communication out to a LPF2 wired device, the user has to add some decoration (CheckSum etc.) to the command packet.

These commands are shown and marked in the main document as shown in the example below:

Output Command 0x81 - HARDWARE RESET Sub Command

Sub Command Value Parameter Description Description

GenericZeroSetHardware()

N/A

Resets or zerosets the H/W component attached to the Port ID

Transmits the universal 0x11 token to the addressed H/W.

Encoded through WriteDirect

6.2.1. Encoding of the prolog part of the command decoration is:¶

Common Header (See Common Message Header).
Startup and Completion information (See description at Startup and Completion Information)
WriteDirect (0x50)
The rest of the message is the Command specific payload.
Checksum - See Checksum Calculation

GENERIC RESET/ZEROSET Command encoded as DirectWrite (Cmd 0x81, Sub Cmd 0x50)
WriteDirect Commands	Encoding	Description
GenericZeroSetHardware()	Port ID, Startup and Completion information, 0x50, 0xD4, 0x11, 0x3A	Send a Reset/zeroset to the device connected to the port specified by the Port ID

6.2.2. Write Direct Example - Zeroset the “sensor” attached to [Port ID]:¶

Zeroset the “sensor” attached to [Port ID]

Port ID, Startup and Completion information, 0x50, 0xD4, RESET, 0x3A

TiltFactoryCalibration Encoded through DirectWrite (Cmd 0x81, Sub Cmd 0x50)
WriteDirect Commands	Encoding	Description
TiltFactoryCalibration(Orientation, PassCode)	0x3A, Startup and Completion information, 0x50, 0xD4, Orientation, “PassCode”, CheckSum	Send calibration command to the Tilt Sensor device connected at the port specified by the Port ID

6.2.3. Write Direct Example - Calibrate Sensor attached to [Port ID]:¶

Calibrate sensor attached to [Port ID]

PassCode = “Calib-Sensor” Orientation: = Z (2)

0x3A, Startup and Completion information, 0x50, 0xD4, 0x02, 0x43, 0x61, 0x6C, 0x69, 0x62, 0x2D, 0x53, 0x65, 0x6E, 0x73, 0x6F, 0x72, 0x77

6.3. Sequence Diagrams¶

6.3.1. Connection Info¶

6.3.2. Combined Mode¶

6.3.3. Port Synchronization¶