Controlling the Raspberry Pi with Android via the WebSocket protocol

WebSocketsServer

The server side of the WebSocket application is written in the C programming language. Thus, C programmers have the option of relying on solutions like libwebsockets [4], wslay [5], or noPoll [6]. Because the authors of libwebsockets advertise their solution as requiring only minimal main memory and little CPU, this library looks like a good fit for the relatively low-powered single-board computer.

The first step is to install the Debian version of Raspbian on the Raspberry Pi using an SD card and then update the operating system via

sudo apt-get update
sudo apt-get upgrade

Directions for doing this can also be found online on many websites [7]. The next step is to compile the components needed to compile libwebsockets for the server side of the WebSocket application.

sudo apt-get install cmake git libssl-dev \
  libglib2.0-dev libjansson4 libjansson-dev

Then, download the source code and compile the libwebsockets library. Listing 1 shows how this is done.

cd $HOME
git clone https://github.com/lukasz-skalski/libwebsockets.git
cd libwebsockets
mkdir build
cd build
cmake -DLWS_IPV6=OFF -DCMAKE_INSTALL_PREFIX:PATH=/usr ..
make
sudo make install

Next, it is a good idea to fetch the important parts of WebSocketsServer from the repository and compile them. Compilation is described in Listing 2.

cd $HOME
git clone https://github.com/lukasz-skalski/WebSocketsServer.git
cd WebSocketsServer
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Debug ../
make

Figure 4 shows the schematics of how the server application works. The WebSocket source code can be divided roughly into five blocks of code. The main() loop of the program starts by initializing the server. This occurs in two stages. Here, you should take into account that libwebsockets offers the high-level API referred to previously.

Figure 4: When initialized, the application creates the WebSockets context and registers with the D-Bus system. The main program then establishes two callback functions for D-Bus and libwebsockets.

Phase 1

To initialize the server, the first step is to augment the fields of the lws_context_creation_info declaration. Then, you can call the libwebsocket_create_context() function as shown in line 30 of Listing 3. Thanks to the selected parameters, socket and handler are created as part of the structure for use by the developer in controlling the connection.

01 [...]
02 static struct libwebsocket_protocols protocols[] = {
03   {
04     "<my_protocol>",                   /* protocol name */
05     <my_callback>,                     /* callback */
06     sizeof(struct per_session_data)  /* max frame size / rx buffer */
07   },
08   {
09     NULL, NULL, 0
10   }
11 };
12 [...]
13
14 struct lws_context_creation_info info;
15 [...]
16 memset (&info, 0, sizeof info);
17 info.port = 8080;
18 info.iface = NULL;
19 info.protocols = protocols;
20 info.extensions = libwebsocket_get_internal_extensions();
21 info.gid = -1;
22 info.uid = -1;
23 info.options = 0;
24 info.ssl_cert_filepath = NULL;
25 info.ssl_private_key_filepath = NULL;
26 [...]
27
28 static struct libwebsocket_context *context;
29
30 context = libwebsocket_create_context (&info);
31 if (context == NULL)
32   {
33     print_log (LOG_ERR, "(main) libwebsocket context init failed\n");
34     goto out;
35   }
36 [...]

This completes the first stage of initialization. Listing 3 (starting at line 16) shows the minimal configuration required for the lws_context_creation_info declaration.

The most basic server capable of establishing communication with a mobile device needs the lws_context_creation_info declaration, the number for the port (info.port) through which the server receives connections, and information about the protocol that is used (info.protocols). The latter points to a structure type libwebsocket_protocols that defines and describes the implemented protocol.

Listing 3 provides an example definition for the my_protocol protocol and the accompanying callback function my_callback() in lines 2 through 11. The definition takes care of opening and closing connections as well as reading and recording data.