Miłosz Orzeł

.net, js, html, arduino, java... no rants or clickbaits.

Setting version of assemblies in ASP.NET MVC application with TeamCity build feature


Last five posts (1, 2, 3, 4, 5) were all about fun stuff with Arduino. Now it’s time for something more mundane ;) In this post I will show you how to create TeamCity build that automatically sets version information in all assemblies produced by ASP.NET application. It's nothing new but I hope to give you some useful background info and note a few gotchas you may face...

Complete code of sample application is available in this GitHub repository.

TeamCity has a build feature called AssemblyInfo patcher that makes setting assembly version easy... This feature is usable on any type of .NET project because it works by updating AssemblyInfo files. Content of such files is used to create version information that .NET Framework uses for picking up correct version of referenced assemblies. Version data is also shown in Windows file properties... Here's a part of AssemblyInfo.cs file which is automatically added by Visual Studio when you create a new project:

// Version information for an assembly consists of the following four values:
//      Major Version
//      Minor Version
//      Build Number
//      Revision
// You can specify all the values or you can default the Revision and Build Numbers
// by using the '*' as shown below:
[assembly: AssemblyVersion("")]
[assembly: AssemblyFileVersion("")]

It contains two attributes: AssemblyVersion and AssemblyFileVersion along with a comment that describes numbering pattern recommended by Microsoft. We will also use another attribute: AssemblyInformationalVersion which is not added by default. AssemblyVersion sets version number that is recognized by .NET for dependency resolution. AssemblyFileVersion is used for file version as seen by Windows and AssemblyInformationalVersion is meant more for human consumption as it can contain strings (we will make use of it for holding Git commit hash)... Detailed description of the meaning of these attributes is outside scope of this post but check this great SO answer if you want to know more.



My test application was created in Visual Studio Community 2013 by using ASP.NET Web Application / MVC project template (C#/.NET 4.5). Two additional projects of Class Library type were added. Here’s how the full solution looks:

Visual Studio solution... Click to enlarge...

Home/Index.cshtml view generated by VS was modified to present version information pulled from three .NET assemblies that are produced by the solution (one is for main web app project and two other are for class libraries). Such div was added to the view:

<div class="row text-primary">
    <div class="col-md-12">
            <dt>Core assembly info:</dt>
            <dt>DataAccess assembly:</dt>
            <dt>Web assembly info:</dt>

You can see some Bootstrap classes there since nowadays Visual Studio templates use Bootstrap framework for styling...

This is how rendered view looks before TeamCity processes AssemblyInfo.cs files:

Version information in web app before TC build... Click to enlarge...

And here's how version info looks after version attributes are modified by build feature:

Version information in web app after TC build... Click to enlarge...

If you wonder how the view gets version info here's HomeController.Index action method: 

public ActionResult Index()
    ViewBag.CoreAssemblyInfo = SomeCoreClass.GetAssemblyInfo();
    ViewBag.DataAccessAssemblyInfo = SomeDataAccessClass.GetAssemblyInfo();

    Assembly assembly = Assembly.GetExecutingAssembly();
    string webAsseblyInfo = string.Format("Full Name = \"{0}\"; Informational Version = \"{1}\"",
                            assembly.FullName, FileVersionInfo.GetVersionInfo(assembly.Location).ProductVersion);
    ViewBag.WebAssemblyInfo = webAsseblyInfo;

    return View();

You can see how the most important assembly version number (the one used by .NET and designated by AssemblyVersion attribute) is a part of assembly's FullName. Informational version (the one that can have strings) is taken with the help of FileVersionInfo class. You can get the number form AssemblyFileVersion attribute too - just check all the interesting stuff that GetVersionInfo method returns... The same kind of code is used in GetAssemblyInfo methods in SomeCoreClass and SomeDataAccessClass.

Ok, so we have our test application - full code is here. Note: I’ve pushed all used Nuget packages to the repository – that takes some space in the repo and might be against recommended way of using Git but it makes TeamCity setup easier. If packages folder is not committed you can expect this type of error during build:

[Csc] App_Start\BundleConfig.cs(2, 18): error CS0234: The type or namespace name 'Optimization' does not exist in the namespace 'System.Web' (are you missing an assembly reference?)

To solve it you would have to restore Nuget packages during build (here’s some info on how to do it).



Now time for build server config! I assume that you have some working knowledge about setting TeamCity build for .NET application so I will discuss only the steps relevant to versioning. I’ve used TeamCity 9.1.3 but don't worry if you have a bit older TC (AssemblyInfo patcher feature exists for a while). I used TC to build code from Git repository checkout on my local drive...

Before setting up AssemblyInfo patcher, add two new build parameters: Minor and Major. These are meant to represent two initial segments of version number and should be set manually - it's your (technical/marketing?) decision whether to name your next version 1.9 or 2.0, right? 

Major and Minor build parameters... Click to enlarge...

Next step is to add AssemblyInfo patcher build feature:

AssemblyInfo patcher build feature... Click to enlarge settings...

And set its properties:

AssemblyInfo patcher settings... Click to enlarge...

I've decided to use such settings:

  • AssemblyVersion:   %Major%.%Minor%.%build.number%
  • AssemblyFileVersion:   %Major%.%Minor%.%build.number%
  • AssemblyInformationalVersion:   %Major%.%Minor%.%build.number%.%build.vcs.number%

You can see that our Major and Minor parameters are used. You can also see the use of TeamCity built-in parameter named build.number. Last attribute contains another TeamCity param: build.vcs.number. It gets version control revision id. I'm using Git so this is a long alphanumerical SHA-1 hash. It means that it cannot be used in setting AssemblyVersion attribute. If you try to do so you will get an error like this:

[Csc] Properties\AssemblyInfo.cs(35, 12): error CS0647: Error emitting 'System.Reflection.AssemblyVersionAttribute' attribute -- 'The version specified '' is invalid'

If you try to use it for AssemblyFileVersion you can expect a warning: 

[Csc] CSC warning CS1607: Assembly generation -- The version '' specified for the 'file version' is not in the normal 'major.minor.build.revision' format

But you can safely use it in AssemblyInformationalVersion as .NET doesn't care if you put letters there... Note: If you work with SVN instead of Git you are lucky because value returned for build.vcs.number is an integer and can be used in all three version-related attributes. If you really need to set revision in AssemblyVersion while using Git you might need to add a custom build step for creating integer id... Let's keep it simple here and leave the last part of version number intact (as 0)...

Once you have AssemblyInfo patcher feature configured and you run the build, you can expect such entries in the build log: 

[22:46:02]Step 1/1: Visual Studio (sln) (2s)
[22:46:02][Step 1/1] Update assembly versions: Scanning checkout directory for assembly information related files to update version to 2.1.14
[22:46:02][Update assembly versions] Updating assembly version in C:\TeamCity\buildAgent\work\8c2a410f7087e36b\.NET\AssemblyInfoTest\AssemblyInfoTest\Properties\AssemblyInfo.cs
[22:46:02][Update assembly versions] Updating assembly version in C:\TeamCity\buildAgent\work\8c2a410f7087e36b\.NET\AssemblyInfoTest\Core\Properties\AssemblyInfo.cs
[22:46:02][Update assembly versions] Updating assembly version in C:\TeamCity\buildAgent\work\8c2a410f7087e36b\.NET\AssemblyInfoTest\DataAccess\Properties\AssemblyInfo.cs

If all went ok your log should also contain something like this:

[22:46:05]Reverting patched assembly versions
[22:46:05][Reverting patched assembly versions] Restoring C:\TeamCity\buildAgent\work\8c2a410f7087e36b\.NET\AssemblyInfoTest\AssemblyInfoTest\Properties\AssemblyInfo.cs
[22:46:05][Reverting patched assembly versions] Restoring C:\TeamCity\buildAgent\work\8c2a410f7087e36b\.NET\AssemblyInfoTest\Core\Properties\AssemblyInfo.cs
[22:46:05][Reverting patched assembly versions] Restoring C:\TeamCity\buildAgent\work\8c2a410f7087e36b\.NET\AssemblyInfoTest\DataAccess\Properties\AssemblyInfo.cs

Don't worry, reverting takes place only in build agent work files. The build artifacts contain properly versioned assemblies. You've seen a proof of that rendered on HTML page, you can also check DLL files properties:

File properties with version information... Click to enlarge...

Properties window shows version set by AssemblyFileVersion and AssemblyInformationalVersion. I have Polish Windows so the properties are labeled Wersja pliku (it means File version) and Wersja produktu (it means Product version).

Keep in mind that AssemblyInfo patcher will not work if version attribute has non-standard format (or AssemblyInfo files are in unusual locations).

Let's say you have something like this (because you keep information about your product in static class constants):

[assembly: AssemblyVersion(ProductInfo.Version)]

You can expect such warning during build:

[Update assembly versions] Assembly info version was specified, but couldn't be patched in file C:\TeamCity\buildAgent\work\8c2a410f7087e36b\.NET\AssemblyInfoTest\AssemblyInfoTest\Properties\AssemblyInfo.cs. Is necessary attribute missing?



And that's all! We have a TeamCity build that sets version information in ASP.NET MVC application assemblies :) 

If somebody will be interested I can write a little supplement to this post in which I will describe how to add version info into zip package (artifact) and how to display it on Team City UI...

[OoB] Controlling gun turret with Spring Boot REST service (Java/Arduino)

This is the fifth post in my little "Out of Boredom" series dedicated to hobby projects with Arduino. Previous posts were all .NET based:

Now it's time for a bit of Java!

I will show you how to use Spring Boot framework to quickly create RESTful web service that can receive JSON requests and send commands to Arduino. The aim is to control a servo and relay based gun turret such as this one:

Gun turret prototype... Click to enlarge...

Click here to get an idea of how such turret operates. The video shows a prototype based on ASG pistol. Don't worry, my aim is quite peaceful: I want to build paintball gun turret :)

I will not discuss any electronics setup or Arduino code in this post. Take a look at the articles linked above to see information about PC-Arduino communication, controlling servos and building relay based circuit... I assume that you know what Spring Boot is, but advanced knowledge is not required to follow this post.

Full code of the project is available on GitHub (includes both Java application and Arduino sketch)...

The easiest way to create basic working Spring Boot project is to use Spring Initializr. I started my project by filling the form like this:

Spring Initializr settings... Click to enlarge...

Note that Gradle is used to create (fat) Jar package, Java 1.8 is used and the only required dependency is Web. This setup will produce an application running on Tomcat Embedded so there's no need for installing any web server. The app has support for REST controllers so we will be able to handle JSON based communication in a clean way with very little effort...


Without further ado, here is the piece of code responsible for receiving messages from clients:

package springarduino;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

public class TurretController {
    private final ArduinoConnection arduino;

    public TurretController(ArduinoConnection arduino) {
        this.arduino = arduino;

    @RequestMapping(value = "turret/execute", method = RequestMethod.POST, consumes = "application/json")
    public TurretResponse executeTurretAction(@RequestBody TurretRequest request) {
        if (request.getPan() < 0 || request.getPan() > 180) {
            throw new IllegalArgumentException("Pan out of 0..180 range (" + request.getPan() + ")");

        if (request.getTilt() < 0 || request.getTilt() > 180) {
            throw new IllegalArgumentException("Tilt out of 0..180 range (" + request.getTilt() + ")");

        boolean sent = arduino.controlTurret(request.getPan(), request.getTilt(), request.isFire());
        if (!sent) {
            throw new RuntimeException("Command not sent :(");

        return new TurretResponse(request.getId(), "Command sent :)");

TurretController class has @RestController annotation and a public method marked with @RequestMapping. The mapping specifies that executeTurretAction method should be invoked whenever a client makes a POST request to .../turret/execute URL. Any HTTP client capable of sending POST with Content-Type="application/json" can communicate with such Spring controller method. It can be some desktop application or a simple HTML page with a bit of jQuery for example. I was using Postman Chrome App to prepare requests. In the next post I will describe how to communicate with such controller from smartphone that runs PhoneGap/AngularJS based application...

executeTurretAction methods expects one argument of type TurretRequest:

package springarduino;

public class TurretRequest {
    private int id;
    private int pan;
    private int tilt;
    private boolean fire;

    // public getters and setters hidden for brevity

If client sends JSON payload such as this:

    "id": "311",
    "pan": "111",
    "tilt": "99",
    "fire": "true"

Spring will take care of creating TurretRequest object. Our service method returns TurretResponse:

package springarduino;

public class TurretResponse {
    private int id;
    private String message;

    public TurretResponse(int id, String message) {
        this.id = id;
        this.message = message;

    // public getters and setters hidden for brevity

If everything goes well, this kind of data will be sent back to client:

    "id": 19,
    "message": "Command sent :)"

You don't have to do anything special to make this happen. Spring chooses HttpMessageConverter implementation to create response in a format that is expected by the client. Another nice feature of our @RestController is the error handling. Let's say that client provides invalid value of tilt angle - this is what is sent back as response:

    "timestamp": 1424382893952,
    "status": 500,
    "error": "Internal Server Error",
    "exception": "java.lang.IllegalArgumentException",
    "message": "Tilt out of 0..180 range (222)",
    "path": "/turret/execute"

Such message is easy to handle in error callbacks (thanks to 500 HTTP status code) and contains useful properties such as message and exception.

Notice that arduino object of ArduinoConnection type is used inside executeTurretAction method. ArduinoConnecton is a Spring bean responsible for communicating with Arduino over serial port.

Our controller gets reference to proper object thanks to Spring's IoC container. TurretController constructor is annotated with @Autowired so Spring knows that ArduinoConnection object needs to be injected.

This is the class responsible for talking to Arduino:

package springarduino;

import gnu.io.NRSerialPort;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;
import java.io.DataOutputStream;

public class ArduinoConnection {
    private static final int MESSAGE_SEPARATOR = 255;

    private final Logger log = LoggerFactory.getLogger(this.getClass());

    private String portName;

    private int baudRate;

    private NRSerialPort serial;

    public void connect() {
        log.info("ArduinoConnection PostConstruct callback: connecting to Arduino...");

        serial = new NRSerialPort(portName, baudRate);

        if (serial.isConnected()) {
            log.info("Arduino connection opened!");

    public void disconnect() {
        log.info("ArduinoConnection PreDestroy callback: disconnecting from Arduino...");

        if (serial != null && serial.isConnected()) {

            if (!serial.isConnected()) {
                log.info("Arduino connection closed!");

    public boolean controlTurret(int pan, int tilt, boolean fire){
        try {
            // Actual values sent to Arduino will be in proper unsigned byte range (0..255)
            byte[] message = new byte[]{(byte) pan, (byte) tilt, (byte) (fire ? 1 : 0), (byte) MESSAGE_SEPARATOR};

            DataOutputStream stream = new DataOutputStream(serial.getOutputStream());

            log.info("Turret control message sent (pan={}, tilt={}, fire={})!", pan, tilt, fire);
            return  true;
        } catch (Exception ex) {
            log.error("Error while sending control message: ", ex);
            return false;

@Component annotation is there to show Spring that ArduinoConnection is a bean and as such Spring should take care of its lifecycle and usage as dependency. By default Spring creates beans in singleton scope. This is fine for us - we only need one such object. connect method is marked with @PostConstruct. This makes the method an initialization callback that gets invoked when ArduinoConnection object is created (it will happen when application is started). @PreDestroy is used on disconnect method to make sure that connection to serial port is released when the program is closed.

controlTurret method is the piece of code that is responsible for sending gun turret action request to Arduino. That method is used in TurretController.executeTurretAction, remember? it uses instance of NRSerialPort to communicate over serial port (gnu.io.NRSerialPort package makes it possible). It comes form NeuronRobotics/nrjavaserial library which is a fork of RXTX that greatly simplifies serial port access. nrjavaserial takes care of loading proper native library needed to access the port (it worked well on my Windows 7 x64). As stated before, I'm not going to discuss Arduino communication and microcontroller code in this post. I will just note that you don't have to worry about casting int to byte while message array is created. It's sad but Java doesn't have unsigned bytes so it will show (byte)MESSAGE_SEPARATOR (which is 255) as -1 while debugging, but a correct value will go over wire to Arduino. Take a look at this screen shot from Free Device Monitoring Studio (you can use this tool to check what data is sent to Arduino through serial port):

Bytes sent to Arduino... Click to enlarge...

Let's get back to ArduinoConnection class: portName and baudRate properties are marked with @Value annotations. This way it is very easy to take the settings from configuration file. All you have to do is to create a file named application.properties in /src/main/resources directory and values will be automatically loaded from config. Here's the content of application.properties file: 

server.address =
server.port = 8090

arduinoPortName = COM3
arduinoBaudRate = 9600

Apart from aforementioned settings for Arduino, there are two other elements, namely: sever.address and server.port. By default Spring Boot runs the application on localhost:8080. I've changed this to custom settings to make it easy to access the application from devices connected to my WiFi network... Accessing TurretController from such devices is the reason why I added following CorsFilter class to the project:

package springarduino;

import org.springframework.stereotype.Component;

import javax.servlet.*;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

public class CorsFilter implements Filter {

    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) throws IOException, ServletException {
        HttpServletResponse response = (HttpServletResponse) res;
        response.setHeader("Access-Control-Allow-Origin", "*");
        response.setHeader("Access-Control-Allow-Methods", "POST, GET, OPTIONS");
        response.setHeader("Access-Control-Max-Age", "3600");
        response.setHeader("Access-Control-Allow-Headers", "X-Requested-With");
        chain.doFilter(req, res);

    public void init(FilterConfig filterConfig) {}

    public void destroy() {}

Thanks to this Cross-Origin Resource Sharing filter it's easy to make ajax calls to executeTurretAction method without using some trickery like JSONP to circumvent same-origin policy restrictions.

And that's it! All interesting elements of the Java web app were discussed. Full code is accessible on GitHub. Since this is Gradle based project, running it is as easy as typing gradlew run. I've included Gradle Wrapper in the repo so you don't even need to have Gradle installed...

[OoB] Moving webcam with joystick and servos (Arduino/SharpDX/WinForms)

Time for the third episode of "Out of Boredom" series :) There was a Sonar project and something about shooting paintballs... This time you will learn how to use Arduino and .NET 4.5 to receive input from joystick and use it to control servos that move a webcam horizontally and vertically!

  • Here you can see a video of the project outcome: Vimeo
  • This repository contains all the code: GitHub

Controlling servos with joystick... Click to enlarge...

How it works? Short version: joystick (in my case Logitech Extreme 3D Pro) is connected to laptop with Windows 7 via USB. Desktop application (.NET 4.5/WinForms) uses SharpDX library (managed DirectX API) to pull position information from joystick. This info is presented in numerical and graphical way on UI (C# 5.0 async helps here). Joy position is then translated into desired pan&tilt servo angles and that data is sent to Arduino Uno through serial port. Arduino receives the data, and thanks to its Servo library, commands servos to move... 

Longer description is split into 2 parts. The first describes desktop app, the second shows Arduino sketch...


1. Desktop application

ServoJoy WinForms application... Click to enlarge...

Main task of the program is to read joystick position. This is easy thanks to SharpDX library that wraps DirectX API so it can be conveniently operated with C#. SharpDX and SharpDX.DirectInput NuGet packages are used in the app. This is the class that contains all the code necessary to monitor joystick movements:

using SharpDX.DirectInput;
using System;
using System.Linq;
using System.Threading;

namespace ServoJoyApp
    public class JoystickMonitor
        private string _joystickName;

        public JoystickMonitor(string joystickName)
            _joystickName = joystickName;

        public void PollJoystick(IProgress<JoystickUpdate> progress, CancellationToken cancellationToken)
            var directInput = new DirectInput();
            DeviceInstance device = directInput.GetDevices(DeviceType.Joystick, DeviceEnumerationFlags.AttachedOnly)
                                        .SingleOrDefault(x => x.ProductName == _joystickName);

            if (device == null)
                throw new Exception(string.Format("No joystick with \"{0}\" name found!", _joystickName));
            var joystick = new Joystick(directInput, device.InstanceGuid);
            joystick.Properties.BufferSize = 128;

            while (!cancellationToken.IsCancellationRequested)
                JoystickUpdate[] states = joystick.GetBufferedData();
                foreach (var state in states)

DirectInput class lets us obtain access to joystick. Its GetDevices method is used to look for an attached joystick with particular name. If such device is found, object of Joystick class gets created. Joystick class has Poll method that fills a buffer containing information about joysticks states. State info comes in a form of JoystickUpdate structure. Such structure can be used to determine what button was pushed or what is the current position in y-axis for example.

Here's an example of reading current joystick position on x-axis:

if (state.Offset == JoystickOffset.X)
      int xAxisPosition = state.Value;

Position is kept in Value property but before using it you have to check what that value means. This can be done by comparing Offset property to desired JoystickOffset enum value. See the docs of JoystickOffset to see what kind of values you can read.

PollJoystick method presented earlier has fallowing signature:

public void PollJoystick(IProgress<JoystickUpdate> progress, CancellationToken cancellationToken)

IProgress generic interface was introduced in .NET 4.5 to allow methods to report task progress. PollJoystick method uses it to notify the rest of the program about changes in joystick state. This is done by progress.Report(state) call. The second parameter (with CancellationToken type) lets as stop joystick polling any time we want. PollJoystick method does it when IsCancellationRequested property of CancellationToken structure is set to true. Is it necessary to use this async-related stuff to poll joystick data? No - it's possible to put joystick polling loop directly in button event handler but then all the work will be executed in UI thread and it will make application unresponsive! Here's how you can run joystick monitoring in modern C#:

private async void btnJoystickMonitorStart_Click(object sender, EventArgs e)
        btnJoystickMonitorStart.Enabled = false;
        btnJoystickMonitorStop.Enabled = true;

        var joystickMonitor = new JoystickMonitor(txtJoystickName.Text.Trim());

        _joystickMonitorCancellation = new CancellationTokenSource();
        var progress = new Progress<JoystickUpdate>(s => ProcessJoystickUpdate(s));
        await Task.Run(() => joystickMonitor.PollJoystick(progress, _joystickMonitorCancellation.Token), _joystickMonitorCancellation.Token);
    catch (Exception ex)
        MessageBox.Show(ex.Message, "Oh no :(", MessageBoxButtons.OK, MessageBoxIcon.Error);

Notice that button even handler is marked with async keyword. Before PollJoystick task is started a new cancellation token is created and ProcessJoystickUpdate is set as a handler for asynchronous task progress notifications. When this setup is done joystick monitoring task is started with await Task.Run call...

This is a part of code responsible for handling joystick state changes:

private void ProcessJoystickUpdate(JoystickUpdate state)
    if (state.Offset == JoystickOffset.X)
        int xAxisPercent = GetAxisValuePercentage(XAxisMax, state.Value);
        pnlXAxisPercent.Width = (int)xAxisPercent;
        lblXAxisPercent.Text = xAxisPercent + "%";
        lblXAxisValue.Text = state.Value.ToString();

        if (rbPanOnXAxis.Checked)
            _panServoPosition = MapAxisValueToPanServoPosition(state.Value, XAxisMax);         
            lblPanServoPosition.Text = _panServoPosition.ToString();
	// ... more ...

As you can see JoysticUpdate structure is used to determine current position in x-axis. UI elements are updated and desired servo position is calculated... If you've looked carefully you might be wondering why if (rbPanOnXAxis.Checked) exists. This is done because the app lets its users decide whether pan (horizontal movement) servo should be bound to x-axis (right-left stick movement) or to zRotation-axis (controlled by twisting wrist on joystick - not all joysticks have this feature).

private byte MapAxisValueToPanServoPosition(double axisValue, double axisMax)
    byte servoValue = (byte)Math.Round((axisValue / axisMax) * (PanServoMax - PanServoMin) + PanServoMin);
    return chkPanInvert.Checked ? (byte)(PanServoMax - servoValue) : servoValue;

Values of my joystick position are reported in 0 to 65535 range but only numbers from 0 to 180 are meaningful for servos I've used. That's why method MapAxisValueToPanServoPosition presented above was created...

Ok, so we are done with detecting joystick movements! Now we need to send desired servo position to Arduino. Fortunately this is really simple thanks to SerialPort component that you can use in WinForms programs. Just drag this component from toolbox and use code as below to control connection with Arduino (spArduino is the name I've given to SerialPort component):

private void btnArduinoConnectionToggle_Click(object sender, EventArgs e)
        if (spArduino.IsOpen)

            btnArduinoConnectionToggle.Text = "Connect";
            spArduino.BaudRate = (int)nudBaudRate.Value;
            spArduino.PortName = txtPortName.Text;

            btnArduinoConnectionToggle.Text = "Disconnect";
    catch (Exception ex)
        MessageBox.Show(ex.Message, "Oh no :(", MessageBoxButtons.OK, MessageBoxIcon.Error);

In my case Arduino is accessible via COM3 port and baud rate of 9600 is sufficient. That's right - despite the fact that the device is connected to PC with USB cable it is accessible via COM port.

Sending servo position to Arduino is really easy:

private void tmServoPosition_Tick(object sender, EventArgs e)
    if (spArduino.IsOpen)
        spArduino.Write(new byte[] { _panServoPosition, _tiltServoPosition, SerialPackagesSeparator }, 0, 3);

spArduino.Write call is used to send an array of three bytes to Arduino. Two values are for requested servo potions and the last one is used to separate the pairs so servo controlling program can always distinguish between pan and tilt values. Writing over serial port is executed inside Tick method of Timer component. This time I didn't bothered with manual creation of background task. I just dragged Timer component and adjusted its Enabled and Interval properties to make the app communicate with Arduino every 10 milliseconds...


2. Arduino sketch

We've discussed an program that can detect joystick movements and send servo position requests over serial port. Now time for a piece of microcontroller software that can actually force servos to move. This is the whole code:

#include <Servo.h>  

const byte setupReadyLedPin = 8;
const byte panServoPin = 10;
const byte tiltServoPin = 12;
const byte separator = 255;

Servo panServo; 
Servo tiltServo; 

void setup() {  
    pinMode(setupReadyLedPin, OUTPUT);
    Serial.begin(9600); // Open connection with PC
    digitalWrite(setupReadyLedPin, HIGH);

void loop() {      
    if (Serial.available() > 2) {            
        byte panAngle = Serial.read();
        byte tiltAngle = Serial.read();
        byte thirdByte = Serial.read();
        if (panAngle != separator && tiltAngle != separator && thirdByte == separator) {         
            // Moving servos

Yup, it's that easy! Servo library is included to allow for panServo and tiltServo objects to be created. These objects (of type Servo) make it possible to command servos to move into desired positions. This is done by calling write method with desired angle, like this:


Before it can be done however, servos have to be assigned to Arduino's output pins. This is achieved by calls to attach method seen in setup function. Digital servos are controlled by duration of ON pulse calculated in 20ms intervals, 1.5ms ON pulse should command a servo to move to the middle... But Servo library does all the heavy lifting for you so you don't have to create proper control signals manually. All you need to do is connect 3 cables each servo has. The servos I own use brown cable for ground, red for plus and orange for control signal. Sonar project used single micro servo so the only power supply needed was the one included in USB. This time two servos are utilized so you should add external power supply. I've connected 1A AC/DC power adapter through a plug that is included on Arduino Uno board and the servos worked really well. Arduino has a built-in fuse that protects USB port from overcurrent (it's a resettable fuse that doesn't allow current bigger than 500mA)...

Communication with .NET application is implemented with Serial class. First, in setup function, a connection is established with Serial.begin(9600) call. Then inside a loop Serial.available method is used to check if packet with servo positions request has arrived from PC. If so, pan&tilt servo angles are read and servos are ordered to move.


This is all that is necessary to control two servos with joystick connected to a computer :) In my project I've used DGServo S3003 servos with pan&tilt bracket to move A4tech PK-910H webcam and I'm really happy with the results! While watching the clip you may think that camera is moving to much compared to joystick movements. Keep in mind however, that servos move in 180 degrees but my joystick operates in smaller range. This is why small stick movement results in big camera swing. Despite that, I was able to control servos position with 1-degree precision quite easily... 

Update 2015-01-11: Click here to see a video of my recent project that has pan and tilt servos used to build gun turret!

[OoB] Shooting paintball marker with relay, Arduino and .NET WinForms

My first Arduino based project was Sonar with C#, JS and HTML5. Now I continue the "Out of Boredom" series with a setup that allows firing a paintball marker (gun) with a command sent from a computer :) This time software stack is simpler - just a small Arduino sketch and uncomplicated WinForms (.NET/C#) application, but hardware requires a bit of electronics knowledge. Don't worry though, nothing too complicated - I'm definitely not an expert in this field... 

Controlling paintball marker with laptop... Click to enlarge...

The project is based around an electromechanical relay. Such relay is basically an electronically controlled switch that allows you to turn powerful devices on and off by sending a signal from Arduino's output pins. You can control very large motors or light bulbs for example. The beauty of this components is the fact that you can govern external circuits - there is no physical link between your control circuit and the thing you want to turn on/off. You can use a relay for devices that require huge current but you can also control more subtle equipment, and that's what I decided to do. I play paintball/speedball and I happen to own high-end electro-pneumatic marker called DM13. Such marker has electronically operated trigger and uses solenoid valve to shoot... I thought: "Wouldn't it be cool to press enter on my laptop and make this gun fire nearly 20 balls per second?"... See this video to see how it worked :)

This is a list of hardware parts used:

Element Role
Arduino Uno R3 Controlling trigger via relay and communicating with PC
JZC-11F 005-IZ SPDT relay Simulating trigger pull by closing trigger circuit
P2N2222AG NPN transistor Supplying current to operate relay 
1.2k Ohm resistor Limiting transistor base current
Green LED Signalling ready state
Red LED Signalling firing 
2x 330 Ohm resistor Limiting current going through diodes
Piezo buzzer Signalling read/fire with different tones
SPST switch Turning buzzer on/off
Breadboard and jumper wires or universal board Connecting components 

And this is the circuit diagram:

Circuit diagram... Click to enlarge...

LED connected to Pin 13 is used to signal that device is ready, LED attached to Pin 12 indicates firing (closed trigger circuit). LEDs are of course not connected to Arduino directly, there are resistors protecting them from overcurrent. Buzzer is there to make one tone when device is ready and another (higher) tone when device is firing. The purpose of a switch is to make your life easier while testing. Buzzer sound can get annoying quickly so you can turn it off...

These are the boring bits, the more interesting stuff is on the left side of the diagram. Pin 2 is connected (via resistor) to a base of NPN transistor and collector is attached to relay coil. The transistor is needed because the coil, which controls the switching function, needs more power then Arduino output pins can supply. In this circuit transistor is used not as amplifier but as a switch. When Pin 2 is set to HIGH (base-emitter voltage = 5V) the transistor reaches its fully-on state and current flows through collector energizing the coil. Putting HIGH state on Pin 2 results in a connection between relay's COM (Common) and NO (Normally Open) pins. I've checked my marker with a multimeter (in resistance mode) and I was able to see that pulling the trigger resulted in a closed circuit between middle and lower pins of the trigger switch. Attaching one cable between middle pin of the switch and COM pin, and another cable between lower switch pin and Normally Open pin gives the ability to simulate trigger pull. In other words: HIGH state on Arduino's Pin 2 equals trigger pull as far as maker is concerned*. It's quite simple but as you've seen on the video it works really well! One more thing: look on the diagram on the right-hand side of JZC-11F relay - there's a signal diode and it's purpose is to protect the transistor from voltage spikes that appear when Pin 2 to is put to LOW state (when supply voltage is removed from relay's coil). Such diode usage is called "flyback" or "freewheeling"... I first created this circuit on a breadboard and then soldered it on a universal board... Keep in mind that there are multiple Arduino relay shields available so you don't really have to create such transistor based circuit yourself. I did it because I think that it's a nice way to refresh some very basic electronics knowledge. Ok, we are done with hardware!

Now time for software (this GitHub repository contains all the code)!

Here's complete Arduino sketch:

const byte fireRelayPin = 2;
const byte fireBuzzerPin = 11;
const byte fireLedPin = 12;
const byte readyLedPin = 13;

const byte readyToFireMessage = 6; // ASCII ACK
const byte fireCommand = 70; // ASCII F
const byte triggerPullDelayInMs = 30;
const byte fireBuzzerHz = 1000;
const byte readyBuzzerHz = 400;

void setup() {  
    pinMode(fireRelayPin, OUTPUT);
    pinMode(fireBuzzerPin, OUTPUT);
    pinMode(fireLedPin, OUTPUT);
    pinMode(readyLedPin, OUTPUT);
    tone(fireBuzzerPin, readyBuzzerHz);  
    digitalWrite(readyLedPin, HIGH); 


void loop() {
   if (Serial.available()) {
        byte data = Serial.read(); 
        if (data == fireCommand) {

void pullTrigger() {
    digitalWrite(fireLedPin, HIGH);    
    digitalWrite(fireRelayPin, HIGH);  
    tone(fireBuzzerPin, fireBuzzerHz);     

void releaseTrigger() {
    digitalWrite(fireLedPin, LOW);    
    digitalWrite(fireRelayPin, LOW);  
    tone(fireBuzzerPin, readyBuzzerHz);  


Nothing complicated :) First, the usual (good) practice of creating constants for pin numbers and other useful values. Then there is a setup method that configures pin modes, initializes serial connection (used to communicate with PC), and turns on the "ready" LED. There is also a call to tune function. tune is used to generate sound by making piezoelectric element in buzzer vibrate at a designated frequency. In loop function program waits for data sent by PC via serial port and checks if this data means a fire command (ASCII letter 'F'). If so, a trigger pull is simulated followed by a slight delay and trigger release. The digitalWrite(fireRelayPin, HIGH); line is what makes paintball gun fire. If you've looked carefully ,you've noticed Serial.write(readyToFireMessage); calls in setup and releaseTrigger functions. These exist to let computer know that Arduino is ready to receive first fire command or is ready to process a new one.

This is the .NET 4.5 WinForms application build to control paintball marker:

Command application... Click to enlarge...

Pressing "Fire" button once makes the marker fire one shot, pressing and holding it makes it fire in a series. How many balls per second will be fired depends of course on triggerPullDelayInMs value, relay speed, marker settings (mine DM13 was setup in semi mode capped to around 20bps), paintball loader speed etc. Shooting is only possible when "Device is ready to fire" shows "YES" and "Safe" checkbox is not ticked.

Here's the code behind the CommandWindow show above (few particularity dull lines removed):

using System;
using System.Drawing;
using System.IO.Ports;
using System.Threading;
using System.Windows.Forms;

namespace PbFireApp
    public partial class CommandWindow : Form
        private const byte ReadyToFireMessage = 6; // ASCII ACK
        private const byte FireCommand = 70; // ASCII F

        private bool _isReadyToFire;
        private bool IsReadyToFire
                return _isReadyToFire;
                _isReadyToFire = value;

        public CommandWindow()
            IsReadyToFire = false;
            spArduino.DataReceived += new SerialDataReceivedEventHandler(DataReceivedHandler);

        private void DataReceivedHandler(object sender, SerialDataReceivedEventArgs e)
            byte data = (byte)spArduino.ReadByte();
            IsReadyToFire = data == ReadyToFireMessage;          

        private void Fire()
            if (!chkSafe.Checked && IsReadyToFire)
                IsReadyToFire = false;
                spArduino.Write(new byte[] { FireCommand }, 0, 1);

        private void btnConnect_Click(object sender, EventArgs e)
                if (spArduino.IsOpen)

                    btnConnect.Text = "Connect";                
                    gbFire.Enabled = false;
                    spArduino.BaudRate = (int)nudBaudRate.Value;
                    spArduino.PortName = txtPortName.Text;


                    btnConnect.Text = "Disconnect";            
                    gbFire.Enabled = true;
            catch (Exception ex)
                MessageBox.Show(ex.ToString(), "Oh no :(", MessageBoxButtons.OK, MessageBoxIcon.Error);
        // ... more ...

        delegate void SetIsReadyToFireLabelCallback();

        private void SetIsReadyToFireLabel()
            if (lblIsReadyToFire.InvokeRequired)
                SetIsReadyToFireLabelCallback d = new SetIsReadyToFireLabelCallback(SetIsReadyToFireLabel);
                Invoke(d, new object[] { });
                lblIsReadyToFire.Text = IsReadyToFire ? "YES" : "NO";
                lblIsReadyToFire.ForeColor = IsReadyToFire ? Color.Orange : Color.Black;

The app is so simple that I decided to put all the code in to form's cs file... SerialPort component is used to communicate with Arduino (I've written a bit more about serial communication in Sonar project posts). Paintball marker is instructed to fire when 'F' command (short for "Fire", ASCII code 70) is sent to Arduino. This line is responsible for it: 

spArduino.Write(new byte[] { FireCommand }, 0, 1);

DataReceivedHandler method is used to set IsReadyToFire property to true when ACK (Acknowledge, ASCII 6) message is obtained from Arduino...

The code is quite obvious except for the SetIsReadyToFireLabel method. Why it is needed? The color and text of a Label control are changed when IsReadyToFire property is set. And that can happen when DataReceivedHandler is executed. We can't directly change UI elements from SerialPort.DataReceived event handler because this will result in an InvalidOperationException with a message such as this: "Cross-thread operation not valid: Control 'lblIsReadyToFire' accessed from a thread other than the thread it was created on.".

And that's it, second "Out of Boredom" project is complete :) 

1. It should be possible to control solenoid valve directly but that would be more complicated and might result in damaging my precious DM13.…

[OoB] Sonar with Arduino, C#, JavaScript and HTML5 (Part 2)

Part 1 described the general idea behind Sonar project, hardware components used and Arduino sketch... This second post in "Out of Boredom" series is about C# and JavaScript programs that make it possible to display ultrasonic range sensor data in web browsers. The role of .NET application is to receive messages from Arduino over serial port and broadcast it to clients using SignalR library. JS/HTML5 clients use jquery.signalR lib to obtain information about servo position with distance to obstacles and use this data to render sonar image on canvas:

Sonar client image... Click to enlarge...

These links are in previous post, but just to remind you:


1. SonarServer 

SonarServer is a .NET 4.5 console app created in Visual Studio Express 2013 for Windows Desktop. It uses Microsoft.AspNet.SignalR.SelfHost and Microsoft.Owin.Cors NuGet packages to create self-hosted SignalR server. ASP.NET SignalR is a library designed to make it easy to create applications that are able to push data to clients running in web browsers. This is in contrast to normal web pages/apps behavior where the client (browser) asks server for action by issuing a request (such as GET or POST). SignalR allows clients to listen for messages send by a server... If possible SignalR will use WebSockets to enable efficient bi-directorial connection. If that option is not available due to either browser or server limitations, it will automatically switch to other push techniques like long polling or Server-Sent Events. When I tested the code on my laptop with Windows 7 Home Premium SP1, long polling was used on IE 11 and SSE in Chrome 37. Server was sending about 20 messages per second and clients didn't have any problems with handling that load (communication was on localhost). Self-hosting means that SignalR server doesn't have to be run on a web server such as IIS - it can exist in plain old console project! If you are completely new to SignalR check this tutorial... 

This is SonarServer project structure:

SonarServer solution...

SonarData.cs file contains such struct:

namespace SonarServer
    public struct SonarData
        public byte Angle { get; set; }
        public byte Distance { get; set; }

Server will send a list of such objects to clients.

SonarHub.cs contains a class derived form Hub. It doesn't declare any methods but is nonetheless useful. Library will use it to generate JavaScript proxy objects...

using Microsoft.AspNet.SignalR;

namespace SonarServer
    public class SonarHub : Hub


Startup.cs file looks like this:

using Microsoft.Owin.Cors;
using Owin;

namespace SonarServer
    class Startup
        public void Configuration(IAppBuilder app)

It configures the SignalR server, letting it support cross-domain connection thanks to UseCors call.

Below are the most important bits of Program.cs file. This code:

using (SerialPort sp = new SerialPort())
     sp.PortName = "COM3";
     sp.ReceivedBytesThreshold = 3;
     sp.DataReceived += new SerialDataReceivedEventHandler(DataReceivedHandler);


     Console.WriteLine("Serial port opened!");

     using (WebApp.Start<Startup>("http://localhost:8080/"))
         Console.WriteLine("Server running!");

is responsible for opening a connection with Arduino over serial port named "COM3" and starting SignalR server on localhost:8080ReceivedBytesThreshold property allows us to control the amount of bytes received from Arduino before DataReceivedHandler is called. You can increase this value if you want bigger packages of data to be broadcasted by server and rendered by clients. This is the part of DataReceivedHandler method that loads serial port data into a byte array:

int count = sp.BytesToRead;
[] data = new byte[count];
sp.Read(data, 0, count);

Such array of bytes is latter on added to custom buffer and processed to create a list of SonarData objects sent to SignalR clients. Part 1 mentioned that Arduino sends data to PC in bytes (array) packages containing three elements: [255, angle, distance]. The purpose of special 255 value is to separate angle-distance pairs of values which are used to create sonar image. We can't just send [angle, distance] stream from Arduino to PC, because the Server could easily loose track of which value is angle and which is distance. This might happen due to delays, buffering etc. Sure it's not a bulletproof protocol but it work well when I tested it. Lot's not get crazy with that - it's a hobby project, remember? :) Check ProcessSonarData method in repository if you want to see how an array of bytes is turned into SonarData list (with buffering taken into account)... 

The last missing piece of SonarServer puzzle is SendSonarDataToClients method:

private static void SendSonarDataToClients(List<SonarData> sonarDataForClients)
    var hub = GlobalHost.ConnectionManager.GetHubContext<SonarHub>();

    Console.WriteLine("Sonar data items sent to clients. Samples count=" + sonarDataForClients.Count);

This is the thing that actually broadcasts data to clients running in web browsers. You may be wondering why SonarHub instance is not created directly with new operator and instead GetHubContext method is used. This is because SignalR is responsible for its hubs life cycle. Such code:

SonarHub sonarHub = new SonarHub();

would result in the exception: System.InvalidOperationException: Using a Hub instance not created by the HubPipeline is unsupported." .


2. SonarClient

SonarClient is the subproject responsible for drawing sonar image. It's not a Visual Studio solution - just a few files:

SonarClient files...

I've tested SonarClient code in IE 11 and Chrome 37 and it worked really well. The assumption is that you run modern browser too. I didn't bother with any feature detection, it's enough for me that I have to write for IE9 at work - well, at least it's not IE 6, huh? ;) But if you want to do such thing I can recommend Modernizr library...

This is content of index.html file (with some boring parts removed for brevity):

<!DOCTYPE html>
    <title>Sonar - sample code from morzel.net blog post</title>
        /* more */
        <canvas id="sonarImage" width="410" height="210"></canvas>

              <!-- more -->            

    <a href="http://morzel.net" target="_blank">morzel.net</a>

    <script src="lib/jquery-1.6.4.js"></script>
    <script src="lib/jquery.signalR-2.1.1.js"></script>
    <script src="http://localhost:8080/signalr/hubs"></script>
    <script src="sonarStats.js"></script>
    <script src="sonarImage.js"></script>
    <script src="sonarConnection.js"></script>

        $(function () {          

Most important bit of this HTML5 markup is the canvas element used to create sonar image. The page imports jquery and jquery.signalR libraries that make it possible to communicate with the Server. That line is particularly interesting:

 <script src="http://localhost:8080/signalr/hubs"></script>

SingalR automatically creates JavaScript proxy objects for server-client messaging, that line lets us load them into page. Last three script references are for JS modules responsible for: displaying info about data received from SonarServer, rendering sonar image and communication with server, respectively. Later there's a short script which initializes the modules after pages DOM is ready.

I will skip the description of sonarStats.js file (nothing fancy there - just filling some table cells). But sonarConnection.js should be interesting for you. This is the whole content:

var sonarConnection = (function () {
    'use strict';

    var sonarHub, startTime, numberOfMessages, numberOfSamples;

    var processSonarData = function (sonarData) {
        $.each(sonarData, function (index, item) {
            sonarImage.draw(item.Angle, item.Distance);
            sonarStats.fillTable(item.Angle, item.Distance, startTime, numberOfMessages, numberOfSamples);

    return {
        init: function (url) {
            $.connection.hub.url = url;

            sonarHub = $.connection.sonarHub;

            if (sonarHub) {
                sonarHub.client.sonarData = processSonarData;
                startTime = new Date();
                numberOfMessages = 0;
                numberOfSamples = 0;

            } else {
                alert('Sonar hub not found! Are you sure the server is working and URL is set correctly?');

The init method sets SignalR hub URL along with sonarData handler and starts a connection with the .NET app. There is also some very basic hub availability check (jquery.signalR library has extensive support for connection related events but lets keep things simple here). processSonarData is invoked in response to Server calling hub.Clients.All.sonarData(sonarDataForClients). The processSonarData function receives an array of objects containing information about servo angle and distance to obstacles. SignalR takes care of proper serialization/deserialization of data - you don't have to play with JSON yourself. $.each function (part of jQuery) is used to invoke sonarImage.draw and sonarStats.fillTable methods for every item in sonarData array...

And here comes the module that changes pairs of angle-distance values into o nice sonar image (whole code of sonarImage.js):

var sonarImage = (function () {
    'use strict';

    var maxDistance = 100;
    var canvas, context;

    var fadeSonarLines = function () {
        var imageData = context.getImageData(0, 0, canvas.width, canvas.height),
            pixels = imageData.data,
            fadeStep = 1,

        for (var i = 0; i < pixels.length; i += 4) {
            green = pixels[i + 1];

            fadedGreen = green - fadeStep;
            pixels[i + 1] = fadedGreen;

        context.putImageData(imageData, 0, 0);

    return {
        init: function (canvasId) {
            canvas = document.getElementById(canvasId);
            context = canvas.getContext('2d');

            context.lineWidth = 2;
            context.strokeStyle = '#00FF00';
            context.fillStyle = "#000000";

            context.fillRect(0, 0, canvas.width, canvas.height);

            context.translate(canvas.width / 2, 0);
            context.scale(2, 2);

        draw: function (angle, distance) {

            context.rotate((90 - angle) * Math.PI / 180);
            context.moveTo(0, 0);
            context.lineTo(0, distance || maxDistance); // Treat 0 as above range



Again we have an init method. It obtains 2d drawing context from canvas and uses it to set line width and color (green). It also sets inner color (black) and fills the whole canvas with it. context.translate call is used to move origin of coordinate system to the middle of canvas (horizontally). By default it sits in upper left corner. context.scale is used to make image two times bigger than it would be drawn in default settings. Read this post if you want to know more about canvas coordinates.

The draw method is invoked for each data sample (angle-distance pair) produced by Arduino and broadcasted with SonarServer. The distance to obstacles measured by HC-SR04 sensor is represented as a line. The bigger the distance the longer the line. This happens thanks to beginPath, moveTo, lineTo, and stroke calls. context.rotate method is responsible for showing the angle in which the sensor was pointing while measuring distance (angle of servo arm). As the servo moves around we want to change the direction in which distance line is drawn. Notice that code responsible for drawing the line is surrounded by context.save and context.restore calls. These two ensure that rotation transformation doesn't accumulate between draw method calls...

fadeSonarLines function is responsible for creating the effect of older sonar lines disappearing in a nice gradual way. context.getImageData method returns an array of RGBA values representing the pixels that create current canvas image. The function loops through image data and progressively reduces the intensity of green color component. This way sonar lines fade to black.

And viola - sonar image can be rendered in a browser :)

Isn't it amazing what is now possible on the web platform? I'm not exactly a dinosaur but I remember when displaying a div overlay on a page required use of hidden iframe (because select elements were otherwise rendered above the overlay)... Crazy times ;)