Teltonika

This extension for Channels implements a set of adapters to encode and decode data from Teltonika devices. The protocol uses different codecs to encode data, of which some are intended for data transmission (device-to-server) and others for generic bi-directional communication. The following data transmission codecs are supported:

• Codec 8
• Codec 8 Extended
• Codec 16

The following generic communication codecs are supported:

• Codec 12
• Codec 13 (device-to-server only)
• Codec 14

Note

Although the extension package is free to use commercially, the source code is not available due to proprietary licensing restrictions. Any violation or attempt to reverse engineer the code will result in legal action.

Getting started

Install the package from NuGet

dotnet add package Faactory.Channels.Teltonika

To enable the decoding of Teltonika packets, use the following to register the middleware with the input pipeline.

IChannelBuilder channel = ...;

channel.AddTeltonikaMiddleware();

Data Types

With the middleware registered, the pipeline will forward specific data types, which you can then use on your own middleware. The data types fall into three categories:

• Identity data
• AVL data
• Message data

Identity data

The first thing that a device sends when it connects is its identity, which is essentially an IMEI. The identity adapter forwards a ModuleId struct, which can be implicitly converted to a string.

Here's an example of how to use the identity data in a handler.

public class MyIdentityHandler : ChannelHandler<ModuleId>
{
    public override Task ExecuteAsync( IChannelContext context, ModuleId data )
    {
        /*
        ModuleId is implicitly convertible to string
        */
        string imei = data;

        /*
        we can use the IMEI to check if the device is allowed to communicate
        if it's in the database, enabled, etc.

        if it's not, we can "reject" the connection by closing the channel
        */
        if ( !IsDeviceAllowed( imei ) )
        {
            return context.Channel.CloseAsync();
        }

        return Task.CompletedTask;
    }
}

AVL data

Periodical device data is decoded from a series of adapters, which is then forwarded as an IAvlData[] array. Each record in the array represents a single data point, which contains its location, a timestamp and a set of IO elements.

Here's an example of a handler for AVL data. Since the base class handles T <--> T[] type mutation, we can choose to handle the data as an array (or IEnumerable) or as a single record.

Warning

When using an older version of the Channels library (before 0.10), we need to handle the data as an array, otherwise, the data sequence order might not be preserved. Using the latest version of the library is recommended. Channels 0.10 was included in version 0.3 of this extension library.

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

Beacons

Teltonika supports protocols from iBeacon and Eddystone. The AVL decoder adapter will automatically decode any beacon data from the IO elements into it's own structure in the IIOData type.

The UUId is a 16-byte unique identifier on both iBeacon and Eddystone. However, on the latter, the UUId is a combination of two fields:

• Namespace (10 bytes)
• Instance (6 bytes)

Eddystone does not support major and minor fields and uses the above instead.

Deprecation warning

In December 2018, Google stopped delivering both Eddystone and Physical Web beacon notifications.

Message data

Messages are decoded from codecs 12, 13 and 14. The adapter forwards them as a IMessageData[] array. Each record in the array represents a single message.

Here's an example of how to use the message data in a handler. Again, since the base class handles T <--> T[] type mutation, we can choose to handle the data as an array or as a single record.

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

Message Builders

The extension library provides a set of message builders to encode data into codecs 12 and 14. These can be accessed through the MessageBuilder static class.

Note

Older versions of the library required additional middleware in the output pipeline. This is no longer necessary. Message builders provide a more flexible and direct way to build messages.

Let's see an example of how to use the message builders to create a Codec 12 message, which is the most common one. The request messages sent from the server to the device always use type 0x05.

/*
Create a new message
*/
IByteBuffer codec12Message = MessageBuilder.Create()
    .AddCodec12Payload( MessageType.Request, customPayload )
    .Build();

/*
Create a new message with a "getinfo" command
*/
IByteBuffer getInfoMessage = MessageBuilder.Create()
    .AddCodec12Payload( MessageType.Request, Encoding.ASCII.GetBytes( "getinfo" ) )
    .Build();

Another example of how to use the message builders to create a Codec 14 message. The difference from Codec 12 is that the IMEI is specified. The device will only answer if the physical device IMEI matches the one specified in the message.

/*
Create a new message with an IMEI specified
*/
IByteBuffer codec14Message = MessageBuilder.Create()
    .AddCodec14Payload( MessageType.Request, customPayload, 355839093124487 )
    .Build();

These messages, once built, can be written to the output pipeline directly, since they are IByteBuffer instances.

IChannel channel = ; // ...

await channel.WriteAsync( codec12Message );

Tachograph

A set of adapters decodes data from generic messages (Codec 12) and forwards it either as a TachoMessage or a specialized type, such as

• TachoStatusMessage
• TachoErrorMessage
• TachoFileBlock

Warning

It is important that firmware version 00.03.79.P1 or higher is used, when using tachograph functionality. Using an older version might result in unwanted behaviour.

Warning

The Tachograph extension is still in development and should not be used in production. Things might still break, change or be removed.