Erlang/OTC - Open Telecom Codec

This library tries to implement encoding and decoding for different (3GPP) telecom protocols. The aim is to support the newest release of each spec, if not stated otherwise.

Encoded format is a binary, and decoded format is a map.

If a field or message is not supported, the library should not crash but instead return some error-tuple or atom.

Decoding should preferably be strict, and follow the rules from the specification. Encoding on the other hand, should be lenient, but if format is incorrect, then log a warning. The idea behind this is that the user knows best what to send, but might need guidance.

Usage

otc can be called with both decode/2, decode/3, as well as decapsulate/2, decapsulate/3 functions. The differens is that decapsulate will crash on errors while decode returns an error-tuple.

In successful cases `decode` will return an ok-tuple containing either (only) a list of headers if the binary was fully decoded, or both a list of decoded headers, and a binary containing the parts it was not able to decode.

1> otc:decode(m2pa, UserBinary).
{ok, {[#{protocol := m2pa, ..}, #{protocol := mtp3, ..}, #{protocol := sccp, ..}], <<SCCPPayload>>}}

2> otc:decode(m2pa, UserBinary, #{stop_after => mtp3}).
{ok, {[#{protocol := m2pa, ..}, #{protocol := mtp3, ..}], <<MTP3Payload>>}}

3> otc:decode(m2pa, LinkBinary).
{ok, [#{protocol := m2pa, ..}]}

4> otc:decapsulate(m2pa, UserBinary).
{[#{protocol := m2pa, ..}, #{protocol := mtp3, ..}, #{protocol := sccp, ..}], <<SCCPPayload>>}

5> otc:decapsulate(m2pa, UserBinary, #{stop_after => mtp3}).
{[#{protocol := m2pa, ..}, #{protocol := mtp3, ..}], <<MTP3Payload>>}

6> otc:decapsulate(m2pa, LinkBinary).
[#{protocol := m2pa, ..}]

For encoding there is only one function encode/1, but it can take multiple different types of inputs.

11> otc:encode(#{protocol => m2pa, ..}).
<<M2PABinary>>

12> otc:encode([#{protocol => m2pa, ..}, #{protocol => mtp3, ..}]).
<<M2PABinary>>

13> otc:encode({[#{protocol => m2pa, ..}], <<M2PAPayload>>}).
<<M2PABinary>>

Examples are given with m2pa codec, but could be used with any of the supported protocols. See [tests](test/otc_tests.erl)

Linguistics

decode - function that converts from binary format to an Erlang map

decapsulate - as decode, but crashes on errors.

parse - function that converts from UMTS magic number to Erlang atom

encode - function that converts from Erlang map to binary format

compose - function that converts from Erlang atom to UMTS magic number

*_codec - modules used as helpers, does not comply with the pkt-style codecs.

Codecs

Name	Spec	Encode	Decode	Production Tested (Decode/Encode)	Notes
M3UA	IETF RFC 4666 September 2006	X	X	D
M2PA	IETF RFC 4165 September 2005	X	X	D
MTP3	ITU-T Q.704 (07/96) July 1996	X	X	D
SCCP	ITU-T Q.713 (03/2001)	X	X
L3	3GPP TS 24.007 v16.5.0	X	X
NAS EPS	3GPP TS 24.301 v16.8.0	/	/		Messages are de-/encoded, but missing parameters
NAS 5GS	3GPP TS 24.501 v16.10.0	/	/		Messages are de-/encoded, but missing parameters
SGSAP	3GPP TS 29.118 v16.0.0

Diameter interfaces

Spec	Interfaces	Notes
3GPP TS 29061	Gi/Sgi
3GPP TS 29061	Gmb
3GPP TS 29061	SGmb
3GPP TS 29109	Zh
3GPP TS 29109	Zn
3GPP TS 29109	Zpn
3GPP TS 29128	T6a/T6b
3GPP TS 29140	MM10
3GPP TS 29153	Ns
3GPP TS 29154	Nta
3GPP TS 29154	Nt
3GPP TS 29172	SLg
3GPP TS 29173	SLh
3GPP TS 29209	Gq
3GPP TS 29211	Rx
3GPP TS 29212	Gx
3GPP TS 29212	Gxx
3GPP TS 29212	S15
3GPP TS 29212	Sd
3GPP TS 29212	St
3GPP TS 29214	Rx
3GPP TS 29215	S9a
3GPP TS 29215	S9a*
3GPP TS 29215	S9
3GPP TS 29217	Np
3GPP TS 29219	Sy
3GPP TS 29229	Cx
3GPP TS 29234	Pr
3GPP TS 29234	Wx
3GPP TS 29272	S13/S13’
3GPP TS 29272	S6a/S6d
3GPP TS 29272	S7a/S7d
3GPP TS 29273	S6b
3GPP TS 29273	STa
3GPP TS 29273	SWm
3GPP TS 29273	SWx
3GPP TS 29283	Diameter Data Management
3GPP TS 29329	Sh
3GPP TS 29336	S6m/S6n
3GPP TS 29336	S6t
3GPP TS 29337	T4
3GPP TS 29338	S6c
3GPP TS 29338	SGd/Gdd
3GPP TS 29344	PC4a
3GPP TS 29345	PC6/PC7
3GPP TS 29368	Tsp
3GPP TS 29388	V4
3GPP TS 29389	V6
3GPP TS 29468	MB2-C
ETSI ES 283 026	Rq
ETSI ES 283 034	e4	Circular dependency/does not compile
ETSI ES 283 035	e2	Circular dependency/does not compile
ETSI ES 283 039-2	GOCAP
ETSI TS 183 017	Gq
ETSI TS 183 059-1	e4
ETSI TS 183 060	Re	Circular dependency/does not compile
ETSI TS 183 066	a4	Circular dependency/does not compile
ETSI TS 183 071	Rr Delegated
ETSI TS 183 071	Rr Request

ASN.1

Name	Spec	Note
MAP v1	GSM 09.02 v4.9.1/ETS 300.599 01-60	correct spec?
MAP v2	GSM 09.02 v4.19.1/ETS 300.599 09-60	correct spec?
MAP v3
MAP v4	3GPP TS 29.002 v16.3.0
CAP v1	GSM Phase 2+ R96
CAP v2	GSM 03.78/3GPP TS 01.441 v7.8.1
CAP v3	3GPP TS 23.078 v4.11.1
CAP v4	3GPP TS 23.078 v16.0.0