Legoino

Disclaimer: LEGO® is a trademark of the LEGO Group of companies which does not sponsor, authorize or endorse this project.

Legoino is an Arduino Library for controlling all kinds of LEGO Powered UP devices. From the two port hub, Move Hub (e.g. Boost), DUPLO train hub, Technic Hub to several devices like distance and color sensor, tilt sensor, train motor, remote control, speedometer, etc. you can control almost everything with that library and your Arduino sketch.

It is also possible to use the "old" Power Function IR Modules and control them via an IR LED connected to a PIN of your ESP32 device. With the Hub emulation function you can even control an "old" Power Function Light or Motor with the Powered Up app.

Arduino Hardware and dependent libraries

The library is implemented for ESP32 boards and uses the ESP32 NimBLE-Arduino library as dependency. This should be installed via the Arduino library manager before using Legoino.

Quickstart

You can find a step by step instruction to your first Legoino project on the following link: Quickstart Tutorial

Breaking Changes

Starting from version 1.0.0 many functions have been renamed and the global variables have been replaced by callback functions. In former versions the reading of sensor values of single or multiple sensors and even reading sensors from different hubs, was not working properly. Due to the changes to the NimBLE-Arduino library the callbacks can now be part of member functions and don't have to be defined globally.

So have a look at the changes and adapt your sketches to the new callbacks. You can find a migration guide here: Migration Guide

If you have questions regarding the migration of your sketches, don't hesitate to use the chat.

Usage Videos

In the following videos you can see with short examples what you can do with the library.

Remote control your Boost model example (just click the image to see the video)

Simple Train example (just click the image to see the video)

Simple Boost movement example (just click the image to see the video)

Simple Hub Emulation example as Bridge from PoweredUp to PowerFunction. With this you have an upgrade of your PowerFunction system and it works like a two Port PoweredUp hub.

Examples

All the included examples are a great source to find a solution or pattern for your problem you want to solve with your Arduino sketch.

You can find different examples in the "examples" folder. You can select the examples in your Arduino IDE via the Menu "File->Examples". Just have a look on the videos to see the examples running :smiley:

• Boost.ino: Example which uses the basic Boost movements (usable with M.T.R. 4 or Vernie model). http://www.youtube.com/watch?v=VgWObhyUmi0
• ColorSensor.ino: Example which reads in the color sensor value (attached to an arbitrary port) and uses the detected color to set the Hub LED accordingly. https://youtu.be/_xCd9Owy1nk
• MoveHubDeviceInfo.ino: Example which displays the various device infos (firmware version, battery level, RSSI, hardware version, tilt) in the serial monitor.
• DistanceSensor.ino: Example which reads in the input of the distance sensor and sets the Hub LED color dependent on the distance. https://youtu.be/TOAQtGGjZ6c
• RotationSensor.ino: Example which reads in the input of the Tacho motor angle to set the Hub LED dependent on the angle to the scale of rainbow colors. https://youtu.be/c3DHpX55uN0
• TrainHub.ino: Example for a PowererdUp Hub to set the speed of a train model. http://www.youtube.com/watch?v=o1hgZQz3go4
• TrainColor.ino: Example of PoweredUp Hub combined with color sensor to control the speed of the train dependent on the detected color. https://youtu.be/GZ0fqe3-Bhw
• HubEmulation.ino: Example of an emulated PoweredUp Hub two port hub (train hub) which could receive signals from the PoweredUp app and will send out the signals as IR commands to a Powerfunction remote receiver. https://www.youtube.com/watch?v=RTNexxT4-yQ
• PoweredUpRemoteAutoDetection.ino: Example of connection of PoweredUp and PoweredUpRemote where the device type is fetched automatically and the order in which you switched on the hubs is no longer relevant.
• ControlPlusHub.ino: Example with connection of ControlPlusHub (TechnicHub) where a Tacho Motor on Port D is controlled.
• Mario.ino Example of connection to a Mario Hub to read in sensor notifications about the Barcode/Tag sensor, Color sensor, Pants sensor and Gesture sensor.

Setup and Usage

Just install the library via the Arduino Library Manager.

First example

Just have a look on the Quickstart Tutorial.

Connection procedure

To setup a connection to your hub, the Hub instance has to be initialized. This will trigger a scan procedure to look if a LEGO Hub is active. If the library found an active hub, it will read out its data (Hub Address, Hub Name, etc.) and changes the state to myHub.isConnecting() == true

Now you are ready to connect to the hub with the command myHub.connectHub();

If the library changes the state to myHub.isConnected() == true you are ready to go and do some cool stuff :grin:

In the setup part of your Arduino sketch, just initialize your Hub:

myHub.init();

In the main loop just add the following connection flow:

  if (myHub.isConnecting()) {
    myHub.connectHub();
    if (myHub.isConnected()) {
      Serial.println("We are now connected to the HUB");
    } else {
      Serial.println("We have failed to connect to the HUB");
    }
  }

Motor Commands

There are different types of motors in the LEGO ecosystem. The Basic Motor (e.g. Train Hub), The Tacho motor and the absolute motor. The prefixes Basic, Tacho and Absolute tell you which command fits for what type of motor. The Tacho Motor commands can also be used with the Absolute motor.

  void stopBasicMotor(byte port);
  void setBasicMotorSpeed(byte port, int speed);

  void setAccelerationProfile(byte port, int16_t time);
  void setDecelerationProfile(byte port, int16_t time);
  void stopTachoMotor(byte port);
  void setTachoMotorSpeed(byte port, int speed, byte maxPower = 100, BrakingStyle brakingStyle = BrakingStyle::BRAKE);
  void setTachoMotorSpeedForTime(byte port, int speed, int16_t time, byte maxPower = 100, BrakingStyle brakingStyle = BrakingStyle::BRAKE);
  void setTachoMotorSpeedForDegrees(byte port, int speed, int32_t degrees, byte maxPower = 100, BrakingStyle brakingStyle = BrakingStyle::BRAKE);
  void setTachoMotorSpeedsForDegrees(int speedLeft, int speedRight, int32_t degrees, byte maxPower = 100, BrakingStyle brakingStyle = BrakingStyle::BRAKE);

  void setAbsoluteMotorPosition(byte port, int speed, int32_t position, byte maxPower = 100, BrakingStyle brakingStyle = BrakingStyle::BRAKE);
  void setAbsoluteMotorEncoderPosition(byte port, int32_t position);

Hub Commands

For some use cases it is required to get the hub address (check a specific hub), the hub type (check a hub type) or the hub name. It is also possible to change the hub name and shutdown the hub.

  NimBLEAddress getHubAddress();
  HubType getHubType();
  std::string getHubName();
  void setHubName(char name[]);
  void shutDownHub();

LED Commands

To control the Hub LEDs, you can use predefined color Variables in the Color enum, RGB values or HSV values with the following commands:

  void setLedColor(Color color);
  void setLedRGBColor(char red, char green, char blue);
  void setLedHSVColor(int hue, double saturation, double value);

Sensor and hub property handling

To get notified about sensor value updates (Button, Hub properties like voltage, RSSI, Tacho motor encoder, Speedometer, color sensor, distance sensor, ...), callback functions are used. After you read the following section you can also have a look into the examples which are included in the library. They are always a good source to find solutions/patterns for problems you want to solve.

Callbacks

To use the callbacks you have to do the following steps. Part of the callback ist the reference of the hub instance. So you can use the hub instance which has triggered the callback function to control attached motors or devices.

Write callback function for port devices

To read in changes of devices which are attached to a port (built-in or external), you have to write a function with the following signa