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 0**MMM** ???? 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.

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:

  1. Lock LPF2 Device for setup (allowing multiple setup of modes without actually changing the mode).
  2. 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.
  3. 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.
  4. 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 N/A 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 N/A
Mode/DataSet[1]
Mode DataSet
MMMM DDDD
Uint8 N/A N/A
Mode/DataSet[n]
Mode DataSet
MMMM DDDD
Uint8 N/A 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 N/A 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 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 Input. Possible values and interpretation depends on the specific Input Type. Uint8 N/A 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 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 N/A
Information Type == SI (003)
SI Range As above SiMin, SiMax [2 * 4 bytes [FLOATING POINT]] N/A 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 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 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 N/A 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 N/A 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 N/A 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”)
assets/LWP_buffering.png
  • 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
(–> [&]_) (Idle) (Idle + completed)
Command for Q –> Busy/Empty Busy/Empty
(–> [&]_) (Idle) (Idle + completed)
Done –> N/A N/A
Interrupy –> N/A N/A
Busy/Empty Command for EI –> Busy/Empty Busy/Empty + discarded
(–> [&]_) (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
–> (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
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

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 N/A
Flash Start Address (LSB): UInt32 N/A N/A
Flash End Address (MSB): UInt32 N/A N/A
The System Type ID for this H/W: UInt8 N/A N/A
Return type and size If Sub Command == 0x66 “Get CheckSum”
Return value

Checksum:

See Checksum Calculation

UInt8 N/A 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 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:

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:

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

assets/5.3.1.png

6.3.2. Combined Mode

assets/5.3.2.png

6.3.3. Port Synchronization

assets/5.4.png