Velleman K8055 TCP Server

Introduction

I have developed a TCP/IP server for the Velleman K8055 card. The server can accept connections from multiple clients, and allows them to execute commands on the Velleman K8055. I designed this server to support an (Android) application I am working on, but the server is flexible enough to support all kinds of clients.

The server will listen for incoming TCP connections on the specified port. Once a connection has been established, the client can authenticate itself with a username and a password. After a successfully authentication, the client can start sending commands to the server.

All communications between the server and the client are transmitted in plain text format. This allows a wide variety of clients. I mainly designed he server to support a smartphone-app I am working on (for Android systems), but the server can also be accept commands from other clients.

The server works very well together with Putty, a well-known Telnet/SSH client for Windows - and Unix platforms. Putty can connect with my server, and allows you to type text-commands. They will be executed immediately.

The server is a Windows-compatible program that should be able to run on all recent Windows-versions. The server has a GUI (Graphical User Interface) that allows you to view the connected clients, and watch a log of all transferred data.

Using the server

You need to install the server on a computer with an connected K8055 card. The computer needs to have a network connection (An Internet-connection is not required if you intent to access the server from your home-network only). The server won't start listening for incoming connections until you click the "Start Server" button.

Now the server is running, and is capable to accept incoming connections from other computers or mobile devices (like tablets or smartphones). These remote computers will need some software that can connect with the server. So you will either need to use a Telnet-client (like putty), or write your own client software. (In the near future I will release a custom Android app for this).

Putty is a freeware client program that can be downloaded from: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html. Just install Putty on the machine from where you want to control the K8055. After starting putty you need to fill in the address of your K8055 server computer: fill in its IP address and the selected server port. Then click "Open" to establish the connection. Now you can start typing in commands, just as you would do in DOS. These commands will be executed on the K8055.

One warning: network communications can be very complex. There is a thing called "Firewalls". Basically a firewall is hardware or software that blocks certain connections to a computer. If you run the K8055 on a computer using a firewall, it might prevent other computers from connecting to it. This can be resolved by adding exceptions to the firewall. A second problem is that many computers aren't connected directly to the Internet. They are connected to a private LAN (Local Area Network) where each computer has a private IP address. Only the router has a public IP address. These private IP addresses cannot be accessed from outside the LAN. In other words: you cannot make incoming connections to them from the Internet. You can often resolve this by setting up "Port Forwarding" on your home router. You can find more information on this external website: http://www.howtogeek.com/66214/how-to-forward-ports-on-your-router

Protocol

I have designed my own protocol for this server. Here are the main characteristics of my protocol:

Each command is transmitted in plain-text format
A line contains a single command. A line is terminated by an enter character (CRLF = Carriage Return + Line Feed).
Commands are not case-sensitive.
Each command is immediately answered by the server. The server will never send data on its own initiative.
Each server-response begins with +OK or -ERR. They indicate whether the command has been executed successfully.
A command can take multiple parameters. Each parameter is separated by a space (except when the space is between quotes).

My protocol has a small instruction set with commands that can be understood by the server. Here is a list of the commands that are currently implemented:

USER <username>
PASS <password>>
QUIT
SetAllDigital
ClearAllDigital
SetDigital <channel>
ClearDigital <channel>
ToggleDigital <channel>
ToggleAllDigital
getAllDigital
getInput <channel>
getAllInputs
setAnalogOutputTo <channel> <value>
clearAnalogOutput <channel> <value>
getAllAnalogOutputs
getAnalogInput <channel>
getAllAnalogInputs

The server responds each command with a single line. A typical response looks like "+OK 101 11111111". The first +OK indicates the command was understood. The second number (101) specifies the server return type: 101 means digital output data, followed by the actual data. In this case "11111111" which means all K8055 outputs channels are currently active.

Security

Access to the server is protected by a username and password. These credentials are transmitted as plain text, so they could be intercepted by people with bad intentions. So I don't recommend to use this server to control critical hardware.

You need to authenticate yourself after connecting in to the server. Authentication is done by transmitting the username and the password to the server. Let's say both username and password are bart. Then you can login to the server using this sequence:

    USER bart
    PASS bart

Programmer's point of view: software architecture

The source code for the project can be downloaded at the bottom of this page. The server is written in Visual Basic .NET, and is targeted for the .NET framework 4.0.

I wrote the server in such a way, that it is very easy to add your own serverfunctions to the source code. To be able to do this, I used a technique called "Reflection": the software will analyze itself , and detect what functions you defined.

Let's take a look at the function SETDIGITAL <channel>. This is a function that allows you to set one of the eight digital output channels. The required code to add this function is:

Here is a short description for the function:

Each user-defined function must be prefixed by Cmd_. This way the server can make a distinction between internal functions and server functions.
A function must have one or more parameters, in this case channel. The type of the parameter will define its allowed values. In our example the type is DigitalOutput, a user-defined type. You can use multiple datatypes here: AnalogInput, AnalogOutput, AnalogValue, DigitalInput, DigitalOutput, ...
A function must have a ServerResponse object as return type. The information from this object will be passed to the client.
The function sets the specified digital output of the K8055, generates a new ServerResponse object and returns it.

Using the .NET reflection technology the server will scan all these Cmd_ functions and the required datatypes. Each datatype specifies the allowed values for a certain parameter. Let me explain this: by specifying a DigitalOutput type, the server knows the expected value is an integer number between 1 and 8 (for each one of the K8055's digital outputs).

You can easily add your own custom functions in the source code, without having to deal with data validation. The server already does this for you. This is possible because of .NET reflection and the usage of inheritance. If this interest you, please check out the source code and watch the class ServerFunctions.vb.

Downloads

Here you can find the downloads for this project. The server itself comes as a complete setup application. The source code is a Visual Studio 2010 Professional project.

Download TCP Server (setup application)

Download TCP Server (source code)