Faactory.Channels.Ruptela 0.1.5

Channels - Ruptela Protocol

This project contains a set of Channels adapters to decode/encode data using Ruptela's protocol.

NOTE: This library is still experimental and should not be used in production.

Learn more about Channels.

Getting started

Install the package from NuGet

dotnet add package Faactory.Channels.Ruptela

To enable decoding of Ruptela packets on the input pipeline, we just need to register the respective adapters with the channel pipeline. We do that with an extension method.

IChannelBuilder builder = ...;

builder.AddRuptelaDecoderAdapters();

With the adapters in place, we need to implement our handlers to handle the correct data. If the message is not known by this implementation, a generic DeviceMessage type is forwarded. The currently known data types are

• Identity Data
• Record data

graph TD
    A[IByteBuffer] --> B[DeviceMessage]
    B --> C{...}
    C --> D[DeviceIdentification]
    C --> E["Record[]"]
    C --> F[TachoData]
    C --> G[TachoFileFragment]
    C --> H[TachoFileInfo]
    C --> I[TransparentData]
    C --> J["DiagnosticTroubleCode[]"]

Identity Data

Even though record messages contain the IMEI in the header, the first thing the device sends is an identification message. The data forwarded to be handled is a DeviceIdentification type. The adapter handles both regular (15) and dynamic (18) identification packets.

If the tracking device is unauthorized, the server sends a NACK response with command 115 (0x73). The tracking device then breaks the link with the server and does not make any further connection attempts until the delay time has passed.

According to Ruptela's documentation, if a device is not authorized, a response should still be sent to the device. This way, the device won't communicate again for a period of time.

Example of an identity handler; notice that the negative response is sent directly to the channel, instead of the output buffer.

public class MyIdentityHandler : ChannelHandler<DeviceIdentification>
{
    public override async Task ExecuteAsync( IChannelContext context, DeviceIdentification data )
    {
        // do whatever we need to do with the identifier
        bool isAllowed = someService.IsDeviceAllowed( data.Imei );

        if ( !isAllowed )
        {
            // let the device know he's not allowed to communicate (write to channel)
            await context.Channel.WriteAsync( MessageBuilder.BuildDeviceAuthorized( false ) );

            // we can also close the channel after responding
            await context.Channel.CloseAsync();
        }
        else
        {
            // let the device know he's allowed to communicate (write to output buffer)
            context.Output.Write( MessageBuilder.BuildDeviceAuthorized() );
        }
    }
}

Record Data

All record data (including extended records) are forwared with the Record type. This type contains a header and the IO elements of the record data.

Since the base handler takes care of T <--> T[] mutation, we can choose to implement our handler with Record[] or Record.

Example of a record handler

public class MyRecordHandler : ChannelHandler<Record[]>
{
    public override Task ExecuteAsync( IChannelContext context, Record[] data )
    {
        // do whatever we need to do
        return Task.CompletedTask;
    }
}

Tachograph Data

Tachograph data can be forwarded as TachoData, TachoFileFragment or TachoFileInfo types.

The TachoData type refers to data sent by the tachograph. This can be for example, authorization data requested by the card reader.

When a file download is requested, it is delivered in fragments. The TachoFileFragment contains the data for each of those fragments. At the end, a TachoFileInfo is sent to complete the process and provide additional information.

Transparent Channel Data

Data received by the device's RS232 interface is forwarded with the TransparentData type.

Diagnostic Trouble Codes

DTCs are forwarded with the DiagnosticTroubleCode type.

Since the base handler takes care of T <--> T[] mutation, we can choose to implement our handler with DiagnosticTroubleCode[] or DiagnosticTroubleCode.

Message Builders

Most of the messages received in the channel require responding back to the device. Although some of these responses are automatically handled by the decoders, such as heartbeats and records, there are some scenarios where building a response message is required. The MessageBuilder type is usually the best way of doing this as it contains a series of known scenarios, as well as a few generic builders that take care of wrapping the payload around Ruptela's protocol.

One example was already provided with the identity data handler. Here's another one to send configuration commands to a device

var buffer = MessageBuilder.BuildDeviceConfiguration( "#cfg_start@" );

// since the build message is a `IByteBuffer` no additional output adapters are required
context.Output.Write( buffer );

There's also a specialized TachoMessageBuilder for tachograph related messages.