MonoBrick Communication Library Programming Guide

This guide descries how to use the MonoBrick communication library with the EV3. Users of the NXT can also use this guide as inspiration as the syntax for the NXT is very similar. Be sure to check the MonoBrick communication library documentation for a complete list of all functionalities for both the EV3 and NXT. This guide contains the following sections.

• Connecting to the brick
• Controlling motors
• Controlling a vehicle
• Reading sensor values
• Using the filesystem
• Miscellaneous

Connecting to the Brick

The examples in this sections shows how to establish a connection to both the EV3 and NXT brick. Before proceeding please make sure that you are able to communicate with the brick. Mac Os and Linux uses will also have to make sure that Mono is installed. The set-up guides found here will help you setup communication under Windows, Linux and Mac OS for use with the MonoBrick communication library.

USB connection

To create a USB connection make sure that you have copied the libusb and the hipapi files that came with the MonoBrick communication library download to the same folder as the exe file. If you are using the MonoBrick communication library test project you do not need to worry about this. The following code will open a usb connection and move motor A.

using System;
using MonoBrick.EV3;

public static class Program{
  static void Main(string[] args)
  {
    var ev3 = new Brick<Sensor,Sensor,Sensor,Sensor>("usb");
    try{
        ev3.Connection.Open();
        ev3.MotorA.On(50);
        System.Threading.Thread.Sleep(3000);
        ev3.MotorA.Off();
    }
    catch(Exception e){
        Console.WriteLine(e.StackTrace);
        Console.WriteLine("Error: " + e.Message);
        Console.WriteLine("Press any key to end...");
        Console.ReadKey();				
    }
    finally{
        ev3.Connection.Close();
    }
  }
}

Bluetooth connection

Before using a bluetooth connection make sure that you have paired your computer with the LEGO Brick. Use the MonoBrick communication library set-up guides to help you with this. On windows the following code will connect to the brick using com6.

var ev3 = new Brick<Sensor,Sensor,Sensor,Sensor>("com6");

Replace this line with line 7 in the usb example to try it out. On Mac Os the bluetooth path might be called something like “/dev/tty.EV3-SerialPort” where EV3 is the name of the EV3 brick or /dev/tty.Great-DevB where Great is the name of the NXT Brick. The code below will create a brick object that connects to the EV3 brick called EV3. Replace this line with line 7 in the usb example to try it out.

var ev3 = Brick<Sensor,Sensor,Sensor,Sensor>("/dev/tty.EV3-SerialPort");

WiFi connection

WiFi connection only works with the EV3 and should not be confused with the tunnel connection which is described below. To use a WiFi connection you need to connect the EV3 to a WiFi network. This guide shows you how to do this. Once the brick is connected to the network replace the following line with line 7 in the usb example.

var ev3 = new Brick<Sensor,Sensor,Sensor,Sensor>("wifi");

Tunnel connection

A tunnel connection lets you communicate with your LEGO brick using either the MonoBrick Tunnel or the MonoBrick Tunnel for Android. This allows you to communicate over both LAN and WAN. Currently the tunnels only supports the NXT but support for the EV3 will be added. Once you have the tunnel connected to the brick use the following code to create a connection to the tunnel listening for clients on a computer with IP-Address 192.168.1.11 on port 1500.

using System;
using MonoBrick.NXT;

public static class Program{
  static void Main(string[] args)
	{
	  var nxt = new Brick<Sensor,Sensor,Sensor,Sensor> ("192.168.1.11",1500);
	  try{
		nxt.Connection.Open();
		nxt.MotorA.On(50);
		System.Threading.Thread.Sleep(3000);
		nxt.MotorA.Off();
	  }
	  catch(Exception e){
		Console.WriteLine(e.StackTrace);
		Console.WriteLine("Error: " + e.Message);
		Console.WriteLine("Press any key to end...");
		Console.ReadKey();				
  	  }
  	  finally{
		nxt.Connection.Close();
  	}
  }
}

If you want to have the tunnel connect to the client if for example the tunnel is running behind a firewall the following code will wait for the trunnel to establish a connection. Replace these two lines with line 6 in the tunnel example above

var connection = new MonoBrick.TunnelConnection<Command,Reply>(1500);
var nxt = new Brick<Sensor,Sensor,Sensor,Sensor>(connection);

To make the tunnel connect to the client please consult the MonoBrick Tunnel page or the MonoBrick Tunnel for Android page.

Controlling motors

Controlling motors with the MonoBrick communication library is easy. In this section the different motor movements are shown including motor synchronisation and vehicle control. The code below demonstrates how to make the motor move forwards, backwards, brake and stop.

var ev3 = new Brick<Sensor,Sensor,Sensor,Sensor>("usb");  
ev3.Connection.Open();
ev3.MotorA.On(50);
System.Threading.Thread.Sleep(3000);
ev3.MotorA.On(-50);
System.Threading.Thread.Sleep(3000);
ev3.MotorA.Brake();//motor is still on but does not move
System.Threading.Thread.Sleep(3000);
ev3.MotorA.Off();
ev3.Connection.Close();

Position control

The following example demonstrates how to make the motor move to relative and absolute positions. When moving to a position please note that if you do not set the break flag the motor will coast when the position is reached and not stop immediately.

using System;
using MonoBrick.EV3;
using System.Threading;
public static class Program{
	static Brick<Sensor,Sensor,Sensor,Sensor> ev3;  
	static void Main(string[] args)
	{
		ev3 = new Brick<Sensor,Sensor,Sensor,Sensor>("usb");
		try{
			ev3.Connection.Open();
			ev3.MotorA.ResetTacho();
			ev3.MotorA.On(50, 6*360,true);
			WaitForMotorToStop();
			Console.WriteLine("Position: " + ev3.MotorA.GetTachoCount());
			ev3.MotorA.On(-50, 9*360, true);
			WaitForMotorToStop ();
			Console.WriteLine("Position: " + ev3.MotorA.GetTachoCount());
			ev3.MotorA.MoveTo(50,0,true);
			WaitForMotorToStop();
			ev3.MotorA.Off();
			Console.WriteLine("Position: " + ev3.MotorA.GetTachoCount());
		}
		catch(Exception e){
			Console.WriteLine(e.StackTrace);
			Console.WriteLine("Error: " + e.Message);
			Console.WriteLine("Press any key to end...");
			Console.ReadKey();				
  		}
  		finally{
			ev3.Connection.Close();
  		}
  	}
  	
  	static void WaitForMotorToStop ()
	{
		Thread.Sleep(500);
		while(ev3.MotorA.IsRunning()){Thread.Sleep(50);}
	}
}

Creating a motor ramp profile

The step profile that is shown in the example makes the motor ramp up in 300 steps, run forward for 600 steps with speed 50, ramps down in 300 steps and brake when done. Profiles that are time based are also supported. See more in the MonoBrick communication library documentation

var ev3 = new Brick<Sensor,Sensor,Sensor,Sensor>("usb");
ev3.Connection.Open();
ev3.MotorA.SpeedProfileStep(50,300,600,300,true);  
ev3.Connection.Close();

Synchronising motors

The example below shows how to synchronise Motor A and Motor D. If you need to synchronise motors to control a vehicle please see the vehicle section below.

var ev3 = new Brick<Sensor,Sensor,Sensor,Sensor>("usb");
ev3.Connection.Open();
ev3.MotorSync.BitField = OutputBitfield.OutA | OutputBitfield.OutD;
ev3.MotorSync.On(50, 0);
System.Threading.Thread.Sleep(3000);
ev3.MotorSync.On(50, 50);//Motor A runs twice as fast as motor D 
System.Threading.Thread.Sleep(3000);
ev3.MotorSync.Brake();
System.Threading.Thread.Sleep(1000);
ev3.MotorSync.StepSync(-50,0,6*360,false);//Move to a position
ev3.Connection.Close();

Controlling a vehicle

This section shows you how to control a vehicle. The example below let’s you control a vehicle using the keyboard. When using this example on your own robot please make sure to change the direction of the motors to fit your needs.

using System;
using MonoBrick.EV3;
using System.Threading;
public static class Program{
	static void Main(string[] args)
	{
		var ev3 = new Brick<Sensor,Sensor,Sensor,Sensor>("usb");
		try{
			ev3.Connection.Open();
			ev3.Vehicle.LeftPort = MotorPort.OutA;
			ev3.Vehicle.RightPort = MotorPort.OutD;
			ev3.Vehicle.ReverseLeft = false;
			ev3.Vehicle.ReverseRight = false;
			sbyte speed = 50;
			ConsoleKeyInfo cki;  
		    Console.WriteLine("Press T to quit");  
		    do   
		    {  
		        cki = Console.ReadKey(true); //press a key  
		        switch(cki.Key){    
		            case ConsoleKey.W:    
		                ev3.Vehicle.Forward(speed);
		            	break;                              
		            case ConsoleKey.S:     
		                ev3.Vehicle.Backward(speed);   
		            	break;    
		            case ConsoleKey.D:     
		                ev3.Vehicle.SpinRight(speed);    
		            	break;    
		            case ConsoleKey.A:     
		                ev3.Vehicle.SpinLeft(speed);    
		            	break;    
		            case ConsoleKey.Q:    
		                ev3.Vehicle.TurnLeftForward(speed, 50);    
		            	break;  
		            case ConsoleKey.E:    
		             	ev3.Vehicle.TurnRightForward(speed,50);       
		            break;  
		            case ConsoleKey.C:    
		                ev3.Vehicle.TurnRightReverse(speed,50);  
		            break;  
		            case ConsoleKey.Z:  
		                ev3.Vehicle.TurnLeftReverse(speed, 50);
		            break; 
		            case ConsoleKey.Spacebar:  
		                ev3.Vehicle.Off();
		            break; 
		        }  
		    } while (cki.Key != ConsoleKey.T);
		}
		catch(Exception e){
			Console.WriteLine(e.StackTrace);
			Console.WriteLine("Error: " + e.Message);
			Console.WriteLine("Press any key to end...");
			Console.ReadKey();				
  		}
  		finally{
			ev3.Connection.Close();
  		}
  	}
}

It is also possible to make the vehicle move a given number of steps as shown below.

ev3.Vehicle.Forward(50,12*360);

Reading sensors

The MonoBrick communication library supports the LEGO sensors that comes with both the EV3 retail and educational sets including the IR-Sensor, Color Sensor, Gyro Sensor and Temperature Sensor. In addition the LEGO sensors from the NXT 1.0 and 2.0 retail sets are also supported including the Light Sensor, Sound Sensor and Ultrasonic sensor. For the NXT a number of Hitechnic are also supported but these are not yet supported on the EV3. This guide only shows how to read sensor values using the EV3. For more information on all supported sensors for the EV3 and how to read sensor values with the NXT please consult the MonoBrick communication library documentation.

All sensors inherits from the sensor base class. The example below uses the base class to print out sensor values

using System;
using MonoBrick.EV3;
using System.Threading;
public static class Program{
	static void Main(string[] args)
	{
		var ev3 = new Brick<Sensor,Sensor,Sensor,Sensor>("usb");
		ev3.Connection.Open();
		ev3.Sensor1 = new IRSensor(IRMode.Proximity);
		ev3.Sensor2 = new TouchSensor();
		ev3.Sensor3 = new ColorSensor(ColorMode.Color);
		ev3.Sensor4 = new GyroSensor(GyroMode.Angle);
		ConsoleKeyInfo cki;  
		Console.WriteLine("Press Q to quit");  
		do   
		{  
	        cki = Console.ReadKey(true); //press a key  
	        switch(cki.Key){    
	            case ConsoleKey.D1://1 is pressed    
	                Console.WriteLine("S1: " + ev3.Sensor1.ReadAsString());
	            	break;                              
	            case ConsoleKey.D2://2 is pressed    
	                Console.WriteLine("S2: " + ev3.Sensor2.ReadAsString());
	            	break;                              
	            case ConsoleKey.D3://3 is pressed    
	                Console.WriteLine("S3: " + ev3.Sensor3.ReadAsString());
	            	break;                              
	            case ConsoleKey.D4://4 is pressed    
	                Console.WriteLine("S4: " + ev3.Sensor4.ReadAsString());
	            	break;                              
	        }  
		} while (cki.Key != ConsoleKey.Q);
		ev3.Connection.Close();
  		
  	}
}

Using generics to set the sensor type

Using generics you can access sensor specific functions as shown in the example below. Here the touch sensor counts bumps and can be cleared by pressing R. The color value is evaluated to determine if the color is in fact green and finally the IR-Sensor is used in seek mode to locate the remote. IR seek mode only works on channel 0.

using System;
using MonoBrick.EV3;
using System.Threading;
public static class Program{
	static void Main(string[] args)
	{
		var ev3 = new Brick<TouchSensor,ColorSensor,IRSensor,Sensor> ("usb");
		ev3.Connection.Open();
		ev3.Sensor1.Mode = TouchMode.Count;
		ev3.Sensor2.Mode = ColorMode.Color;
		ev3.Sensor3.Mode = IRMode.Seek;
		ConsoleKeyInfo cki;  
		Console.WriteLine("Press Q to quit");  
		do   
		{  
	        cki = Console.ReadKey(true); //press a key  
	        switch(cki.Key){    
	            case ConsoleKey.R://C is pressed    
	                ev3.Sensor1.Reset();//reset the count
	                Console.WriteLine("Reset touch count");
	            	break;                              
	            case ConsoleKey.D1://1 is pressed    
	                Console.WriteLine("S1: " + ev3.Sensor1.ReadAsString());
	            	break;                              
	            case ConsoleKey.D2://2 is pressed    
	                Color color = ev3.Sensor2.ReadColor();
	                if(color == Color.Green){
	                	Console.WriteLine("Color is green");
	                	ev3.Beep(50,100);
	                }
	                else{
	                	Console.WriteLine("Color is " + color +  
	                	" and this is not green");
	                }
	                break;                              
	            case ConsoleKey.D3://3 is pressed    
	                int value  = ev3.Sensor3.Read();
	                if(value == 0){
	                	ev3.Beep(50,100);
	                	Console.WriteLine("Found target");
	                }
	                else{
	                	if(value < 0){
	                		Console.WriteLine("Target is to the left");
	                	}
	                	else{
	                		Console.WriteLine("Target is to the right");
	                	}
	                }
	            	break;                              
	        }  
		} while (cki.Key != ConsoleKey.Q);
		ev3.Connection.Close();
  	}
}

Auto detecting sensor type

The following example shows how to auto detect the sensor type and assign the sensor to the correct type. This makes it possible to print the value in the correct format.

using System;
using MonoBrick.EV3;
using System.Threading;
public static class Program{
	static void Main(string[] args)
	{
		var ev3 = new Brick<Sensor,Sensor,Sensor,Sensor>("usb");
		ev3.Connection.Open();
		Sensor newSensor = null;
		string key = SensorHelper.TypeToKey(ev3.Sensor1.GetSensorType());
		if(SensorHelper.SensorDictionary.TryGetValue(key, out newSensor)){
			ev3.Sensor1 = newSensor;
		}
		ConsoleKeyInfo cki;  
		Console.WriteLine("Press Q to quit");  
		do   
		{  
	        cki = Console.ReadKey(true); //press a key  
	        switch(cki.Key){    
	            case ConsoleKey.D1://1 is pressed    
	                Console.WriteLine("S1: " + ev3.Sensor1.ReadAsString());
	            	break;                              
	        }  
		} while (cki.Key != ConsoleKey.Q);
		ev3.Connection.Close();
  		
  	}
}

Using the filesystem

With the filesystem it is possible to start and stop programs, get a list of files and playback sound files. Below some sample code for listing subfolders and files in the project folder is shown.

using System;
using MonoBrick.EV3;
using System.Threading;
public static class Program{
	static void Main(string[] args)
	{
		var ev3 = new Brick<Sensor,Sensor,Sensor,Sensor>("usb");
		ev3.Connection.Open();
		BrickFile[] files;
		string[] subfolders;
		ev3.FileSystem.GetFolderInfo("/home/root/lms2012/prjs/", 
									out files, out subfolders);
		Console.WriteLine("Files:");
		foreach(var file in files){
			Console.WriteLine(file.Name);
		}
		Console.WriteLine(Environment.NewLine + "Subfolders:");
		foreach(var folder in subfolders){
			Console.WriteLine(folder);
		}
		ev3.Connection.Close();
  	}
}

Create a directory and write a file to the EV3

var ev3 = new Brick<Sensor,Sensor,Sensor,Sensor<("usb");
ev3.Connection.Open();
ev3.FileSystem.CreateDirectory("/home/root/lms2012/prjs/MyPrograms");
ev3.FileSystem.WriteFile(@"C:\program.rbf",
                         "/home/root/lms2012/prjs/MyPrograms/program.rbf"); 
ev3.Connection.Close();

Recursively listing program files found in /home or its subfolders

This example require linq to be included in the project. In Visual Studio this is default while Mono Users will have to add a reference to System.Core

var ev3 = new Brick<Sensor,Sensor,Sensor,Sensor<("usb");
ev3.Connection.Open();
var folderStructure = ev3.FileSystem.GetFolderStructure("/home");
var fileQuery = from structure in folderStructure.RunThroughFolders()
                from files in structure.FileList
                where files.FileType == MonoBrick.FileType.Program
                select files;
foreach(var file in fileQuery)
    Console.WriteLine(file.Name + " in " + file.Path);
ev3.Connection.Close();

Starting and stopping the first program found in /home or its subfolders

This example require linq to be included in the project. In Visual Studio this is default while Mono Users will have to add a reference to System.Core

var ev3 = new Brick<Sensor,Sensor,Sensor,Sensor<("usb");
ev3.Connection.Open();
var folderStructure = ev3.FileSystem.GetFolderStructure("/home");
var fileQuery = from structure in folderStructure.RunThroughFolders()
                from files in structure.FileList
                where files.FileType == MonoBrick.FileType.Program
                select files;
ev3.StartProgram(fileQuery.First());
System.Threading.Thread.Sleep(5000);
ev3.StopProgram();
ev3.Connection.Close();

Miscellaneous

Sending data to the mailbox

To make the EV3 receive data from the mailbox a program must be running on the brick that listens for data from the mailbox. Use the download link to get a hold of the EV3 program shown below. The program simply takes the input string from the mailbox named "mailbox1" and prints it on the LCD.

To send text to the EV3 the following code can be used.

using System;
using MonoBrick.EV3;
using System.Threading;
public static class Program{
  static void Main(string[] args)
  {
      var ev3 = new Brick<Sensor,Sensor,Sensor,Sensor<("usb");
      ev3.Connection.Open();
      ConsoleKeyInfo cki;
      Console.WriteLine("Press Q to quit");    
      do     
      {    
          cki = Console.ReadKey(true); //press a key    
          switch(cki.Key){
            case ConsoleKey.M:
                Console.WriteLine("String to send to mailbox");
                string input = Console.ReadLine();
                ev3.Mailbox.Send("mailbox1", input, false);
                break;                                 
          }    
      } while (cki.Key != ConsoleKey.Q);  
      ev3.Connection.Close();
  }
}

Controlling bricks connected in a daisychain

using System;
using MonoBrick.EV3;
using System.Threading;
public static class Program{
  static void Main(string[] args)
  {
      var ev3 = new Brick<Sensor,Sensor,Sensor,Sensor<("usb");
      ev3.Connection.Open();
      ev3.MotorA.DaisyChainLayer = DaisyChainLayer.First;
      ev3.MotorA.On(50);
      Thread.Sleep(2000);
      ev3.MotorA.Off();
      ev3.Sensor1.DaisyChainLayer = DaisyChainLayer.Second;
      Console.WriteLine(ev3.Sensor1.ReadAsString());
      ev3.Connection.Close();
  }
}