LEGO C# SDK – Enhancements & Challenges

Recap

This is a follow-up to my previous post discussing how I went about creating a C# SDK for the most recent version of the LEGO specification for the Bluetooth (Low Energy) protocol used in a range of their PoweredUp products. Read more here.

Inputs (Sensors)

The biggest improvement so far has been the work to read sensory data from connected devices. There is a lot of upstream and downstream messages required to coordinate this which I detail below for those that are interested.

Input Modes

The input modes are a logical separation allowing a single connected device (e.g. motor) to have different modes of operation for which you can send (output) or receive (input) data.

The protocol allows us to interact with the connected device using either a single mode (e.g. Speed) or a combined mode where supported (e.g. Speed, Absolute Position, and Position).

Single Input

To use single input mode we need to set the desired input mode, delta to trigger updates, and flag whether to notify us (push data) or not (poll data).

This is done by sending a Port Input Format Setup (Single) message which contains:

• Port # of the connected device (e.g. 0)
• Mode we wish to set (e.g. Mode 1 / Speed)
• Delta of change which should trigger an update (e.g. 1)
• Notify flag whether to automatically send an upstream message when the delta is met.

You can be quite creative using single input. We can calibrate the min and max position of a linear actuator by switching the input modes as below:

1. Switch input mode to Speed.
2. Move to absolute minimum position using a lower than normal power (torque).
3. Monitor changes to Speed until value drops to 0.
4. Switch input mode to Position.
5. Record current position as calibrated minimum for device.
6. Switch input mode to Speed.
7. Move to absolute maximum position using a lower than normal power (torque).
8. Monitor changes to Speed until value drops to 0.
9. Switch input mode to Position.
10. Record current position as calibrated maximum for device.

These recorded min and max positions can be stored in the SDK against the device to act as constraints for further commands before they are forwarded onto the hub.

Combined Input(s)

Whilst single input is really simple to setup and can be used to make the connected device behave much more intelligently, it is inconvenient and inefficient to have to keep switching modes.

Combining modes allows us to inform the device what combination of modes we are interested in (based on a supported range of options) and receive a message that contains information (data sets) about all modes consolidated.

The setup of this is much more complicated based on how much information is device specific.

Prerequisites

Information about the connected device can be obtained by sending a Port Information Request message. We actually send this message twice so that we can obtain different information types:

• Port Information
• Possible Mode Combinations

Port Information provides information from the connected device about general capabilities (e.g. input, output, combinable, synchronizable) and the modes of operation for input and output.

Based on the the port having the capability of being combinable the subsequent message provides information about the range of mode combinations supported (e.g. Mode 1 + Mode 2 + Mode 3). We will need to reference which of these mode combinations we want to utilize later on.

Once we have this information we can determine how to interact with each mode. The main thing we are interested in for the purpose of combining inputs is the value format which communicates how many data sets to expect, the structure of the data etc.

To obtain this information we send a Port Mode Information Request message for each mode. This message contains:

• Port
• Mode
• Information Type (e.g. Value Format)

The message will trigger a response which we can intercept. In the case of Value Format we get the following information:

• Number of data sets
• Data type (e.g. 8 bit)
• Total figures
• Decimals (if any)

With this information we should have everything we need to setup our combined input(s).

Setup

For combined input(s) the setup requires several messages.

Firstly we must lock the device to avoid subsequent steps from being treat as a single input setup. This is done using a Port Input Format Setup (Combined) message with the Lock LPF2 Device for setup sub-command.

Then, for each mode we wish to combine we need to send the Port Input Format Setup (Single) as detailed above.

Before we unlock the device we need to configure how the data sets will be delivered using another Port Input Format Setup (Combined) message, this time with the SetModeDataSet combination(s) sub-command.

This includes the combination mode we wish to use along with an ordered mapping of modes and data sets that we wish to consume.

An example payload could be:

• 9 = Message Length
• 0 = Hub Id
• 66 = Message Type : Port Input Format Setup (Combined)
• 0 = Port #
• 1 = Sub-Command : SetModeDataSet combination(s)
• 0 = Combination Mode Index
• 17 = Mode/DataSet[0] (1/1)
• 33 = Mode/DataSet[1] (2/1)
• 29 = Mode/DataSet[2] (3/1)

Note: This should trigger a response message to acknowledge the command but I do not receive anything currently. Issue logged here in GitHub.

Finally, the device is unlocked using a third Port Input Format Setup (Combined) message with either UnlockAndStartWithMultiUpdateEnabled or UnlockAndStartWithMultiUpdateDisabled sub-commands.

Routines

Routines are simply a way to encapsulate reusable scripts into classes that can be run against devices and optionally awaited.

A good example of a routine is range calibration. By encapsulating the routine we can just apply it to as many devices as required any use constructor parameters for configuring the routine.

A routine has start and stop conditions which allow us to create iterative routines that are designed to repeat steps a number of times before completing.

It’s also possible to make the start and/or stop conditions dependent on the state of the device. For example, you could have a routine that stopped once the Speed dropped to zero etc.

Next Steps

I am keen to complete the combined input(s) setup once I have resolved the issue in GitHub. That will allow me to simplify the range calibration routine and start to create additional routines that are more dynamic and intelligent.

I also want to introduce a mechanism to relate control interfaces with commands and routines but before that I will probably need to implement a message buffer in the SDK to ensure that we can throttle downstream messages based on the limitations of the hubs capacity to process them.

C# SDK for LEGO Bluetooth (LE) Hubs

Tl;dr See the source code (and contribute) on Github.

LEGO & Bluetooth (LE)

LEGO have a new standard for communicating over Bluetooth (Low Energy) with compatible smart hubs that is documented here. The documentation is not being kept up to date but there is enough information there to fill in the gaps using a bit of trial and error.

Some of the older powered components use a different protocol and/or wiring specification. It is not the purpose of this post to document compatibility. I will detail any components I used during my development however.

Project Goal

The specification provides a good amount of detail but there are presently no C# SDKs to allow me to connect to a LEGO hub and control its connected devices remotely using a high level API.

As an example, I would like to be able to do the following…

	using (var connectionManager = new BluetoothLEConnectionManager())
	{
	var connectionA = await connectionManager.FindConnectionById("BluetoothLE#BluetoothLEb8:31:b5:93:3c:8c-90:84:2b:4d:d2:62");
	var connectionB = await connectionManager.FindConnectionById("BluetoothLE#BluetoothLEb8:31:b5:93:3c:8c-90:84:2b:4e:1b:dd");
	var hubA = new TechnicSmartHub(connectionA);
	var hubB = new TechnicSmartHub(connectionB);
	// wait until connected
	await hubA.Connect();
	await hubB.Connect();
	// wait until all 3 motors are connected to Hub A
	var leftTrack = await hubA.PortA<TechnicMotorXL>();
	var rightTrack = await hubA.PortB<TechnicMotorXL>();
	var turntable = await hubA.PortD<TechnicMotorL>();
	// wait until all 4 motors are connected to Hub B
	var primaryBoom = await hubB.PortA<TechnicMotorXL>();
	var secondaryBoom = await hubB.PortB<TechnicMotorL>();
	var tertiaryBoom = await hubB.PortC<TechnicMotorL>();
	var bucket = await hubB.PortD<TechnicMotorL>();
	// sequentially calibrate each linear actuator using a torque based range calibration routine
	await primaryBoom.RunRoutine(new RangeCalibrationRoutine(50));
	await secondaryBoom.RunRoutine(new RangeCalibrationRoutine(50));
	await tertiaryBoom.RunRoutine(new RangeCalibrationRoutine(40));
	await bucket.RunRoutine(new RangeCalibrationRoutine(35));
	// move forwards for 5 seconds
	leftTrack.SetSpeedForDuration(50, 100, RotateDirection.Clockwise, 5000);
	rightTrack.SetSpeedForDuration(50, 100, RotateDirection.CounterClockwise, 5000);
	await Task.Delay(5000);
	// rotate boom for 3 seconds
	turntable.SetSpeedForDuration(100, 100, RotateDirection.CounterClockwise, 3000);
	await Task.Delay(3000);
	// reposition boom
	primaryBoom.SetSpeedForDuration(100, 100, RotateDirection.Clockwise, 3000);
	secondaryBoom.SetSpeedForDuration(75, 100, RotateDirection.CounterClockwise, 3000);
	tertiaryBoom.SetSpeedForDuration(100, 100, RotateDirection.CounterClockwise, 2000);
	await Task.Delay(3000);
	// lift bucket
	bucket.SetSpeedForDuration(50, 100, RotateDirection.Clockwise, 2000);
	}

view raw

Example.cs

hosted with ❤ by GitHub

I want to abstract the SDK from the connection so that I can distribute the Core as a .NET Standard package that can be used by different application types (e.g. UWP or Xamarin).

It should be possible to interact at a low level issuing commands in a procedural manner but provide an opportunity to eventually register additional information about the model being controlled so that more intelligent instructions can be executed using calibrated constraints and synchronized ports etc.

For this project I used the LEGO Technic set: Liebherr R 9800 (41200). It comes bundled with:

• 2 x LEGO Technic Smart Hub (6142536)
• 4 x LEGO Technic Motor L (6214085)
• 3 x LEGO Technic Motor XL (6214088)

A Control+ application provides connectivity with the model but isn’t extensible or compatibility with custom builds. Other applications provide basic programming capabilities using arrangements of blocks but this will be the only C# SDK to provide more control to users without being dependent on iOS or Android app support.

Functional Overview

Based on the model referenced above, the Control+ components are connected as below:

Each Hub/Port controls different aspects of the model as follows:

• Hub A
  • Port A : Left track
  • Port B : Right track
  • Port D : Turntable
• Hub B
  • Port A : Primary Boom
  • Port B : Secondary Boom
  • Port C : Tertiary Boom
  • Port D : Bucket

SDK Types

In order to facilitate interop between the SDK and the remote hubs we will have the following types:

IConnection

This interface abstracts the BluetoothLE device connection from the SDK so that it can be used to subscribe to notifications and to read or write values without us being tightly coupled to a specific implementation (e.g. UWP).

Each IConnection has a one to one relationship with a BluetoothLE device based on the device ID.

IMessage

An IMessage is a byte[] that encapsulates all IO communication between the physical hub and the derived Hub class(es). Different concrete implementations provide strongly typed properties (usually enums) to make the interop more readable and to simplify parsing the byte streams.

Hub

This is an abstract class that all specific Hubs must implement and it encapsulates the interactions between the Hub and its assigned IConnection.

A Hub is responsible for taking actions based on messages it received from the IConnection and for writing values based on any outbound IMessage the Hub produces.

Device

This represents anything which can be connected to the Hub either by a physical port (e.g. Motor) or a virtual port (e.g. Internal sensor).

Each concrete implementation of a Device must correspond with an IODeviceType enum value since the Hub will be responsible for instantiating a Device and assigning it to a port.

Devices can produce messages and extensions expose convenience methods based on composition interfaces (e.g. IMotor).

Video Example

More Information

For the source code, please see the Github repo: https://github.com/Vouzamo/Lego

If anyone would like to become a contributor that would be much appreciated as this will be the communication standard for all LEGO hubs moving forward and I would like to get this working for all the potential hubs and devices available.

Other enhancement could include:

• Registration of control components to for real-time user input.
• Registration of virtual components for real-time API input (e.g. RESTful).
• Registration of device constraints to manage calibration for absolute extremes to constrain what commands can be sent to the hub for a given port/device.
• Registration of device commands that should be invoked based on Hub state or incoming IMessage conditions.