* 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.
#+BEGIN_SRC erlang
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, ..}]
#+END_SRC
For encoding there is only one function encode/1, but it can take
multiple different types of inputs.
#+BEGIN_SRC erlang
11> otc:encode(#{protocol => m2pa, ..}).
<<M2PABinary>>
12> otc:encode([#{protocol => m2pa, ..}, #{protocol => mtp3, ..}]).
<<M2PABinary>>
13> otc:encode({[#{protocol => m2pa, ..}], <<M2PAPayload>>}).
<<M2PABinary>>
#+END_SRC
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 | |
| | | |
