Messaging

Network messaging

As we know, WOWCube consists of eight modules, and each module is a separate independent micro-computer with its own processor, memory and storage space. Obviously, the modules must be able to interact and transfer information to each other, how else can we possibly create really high-quality games?

Such a connection between modules certainly exists.

In much the same way as in the case of a conventional network, computers are connected with network cables, the WOWCube modules are connected by UART channels.

Without much digging into technical details, UART, or universal asynchronous receiver-transmitter, is a device-to-device communication protocol, one of the most used ones too.

By definition, UART is a hardware communication protocol that uses asynchronous serial communication with configurable speed. Asynchronous means there is no clock signal to synchronize the output bits from the transmitting device going to the receiving end.

The purpose of a transmitter and receiver channel for each device is to transmit and receive serial data intended for serial communication.

So as you can see, the analogy with ordinary network is pretty close. The modules are connected via UART channels, these connections form an internal "network" inside WOWCube device. The only difference is, each module has three adjoined modules, therefore each module must have three UART channels to be able to talk to all its neighbours.

The example

In this example we actually want to do rather simple, but very important thing which takes an essential part in the architecture of many WOWCube games - we want to send a message from one module to the other. I mean, once you know how to do that, you know how to send many more messages wherever and whenever you need to, right?

So let's begin.

Firstly, we define commands we want to be able to send from one module to the other:

1enum Commands
2{
3    cmd_paintGreen = 1,
4    cmd_paintBlue = 2,
5    cmd_paintRed = 3
6};
7 

This is more for convenience really. Nothing stops us from sending of some raw data, some decimal number or floats. But the code would look tidier if you just give a bit of a human readable description to these values.

So yeah, we've defined three commands.

But how to use them? What exactly to command?

The answer is, we will command one module from the other one. One module asks to do something - the other does it. One module sends commands - the other one receives them.

Simple.

How the commanding module knows it should send the command? Even simple, it will do that on tap. You tap it - and it sends the command to use another color.

In order to handle screen taps, on_Tap(uint32_t count) callback function is used:

1void Messaging::on_Tap(uint32_t count) 
2{
3    if (this->Module == 0) 
4    {
5        //When device is tapped, module 0 will broadcast commands to all neighbouring modules
6        this->sendDataToNeighbours();
7    }
8    else
9    {
10    }
11}
12 

and the sendDataToNeighbours() function is called to broadcast current command to the adjoined modules.

1void Messaging::sendDataToNeighbours()
2{
3    Cubios::NetworkMessage message;
4 
5    //we will send empty network messages with different commands to all neighbours
6    switch(this->counter)
7    {
8        case 0: this->SendNetworkMessage(Commands::cmd_paintBlue, &message); break;
9        case 1: this->SendNetworkMessage(Commands::cmd_paintGreen, &message); break;
10        case 2: this->SendNetworkMessage(Commands::cmd_paintRed, &message); break;
11        default:
12        break;
13    }
14    
15    if(this->counter<2) this->counter++; else this->counter = 0;
16}
17 

Now, to receive the message, void Messaging::on_Message(uint32_t type, uint8_t* pkt, u32_t size) callback is used. It gets called every time when WOWCube module receives data over UART channels.

1void Messaging::on_Message(uint32_t type, uint8_t* pkt, u32_t size) 
2{
3    if(this->Module!=0)
4    {
5        switch(type)
6        {
7            case Commands::cmd_paintBlue: this->currentColor = Colors::blue; break;
8            case Commands::cmd_paintGreen: this->currentColor = Colors::green; break;
9            case Commands::cmd_paintRed: this->currentColor = Colors::red; break;
10            default: break;
11        }
12    }
13}
14 

And finally, in order for us to know that the message has been sent and received successfully, let's give some visual feedback:

1void Messaging::on_Render(std::array<Cubios::Screen, 3>& screens)
2{
3    for(auto it = screens.begin(); it != screens.end(); ++it)
4    {
5        Cubios::GFX_setRenderTarget(it->ID());
6 
7        if(this->Module == 0)
8        {
9                Cubios::GFX_clear(Colors::red);
10                Cubios::GFX_drawText(120,80, 14, 0, Cubios::text_align_t::TEXT_ALIGN_CENTER, Colors::white, "TAP");
11                Cubios::GFX_drawText(120,160, 14, 0, Cubios::text_align_t::TEXT_ALIGN_CENTER, Colors::white, "ME");
12        }
13        else
14        {
15            Cubios::GFX_clear(this->currentColor);
16        }
17 
18        Cubios::GFX_render();
19    }
20}
21