trm/tcp-ingestion
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Implement Phase 1 tasks 1.5-1.7 + 1.9 (Codec 8/8E/16 parsers + fixture suite)

Browse Source 
- Codec 8 parser (1-byte IO IDs, no NX/Generation Type)
- Codec 8 Extended parser (2-byte IO IDs + variable-length NX section)
- Codec 16 parser (mixed widths + Generation Type, supports IO IDs > 255)
- Shared GPS element / timestamp helpers in gps-element.ts
- Fixture loader with bigint/Buffer sentinel encoding and auto-discovery
- 12 fixture pairs across codec8/8E/16 (canonical doc + synthetic edge cases)
- Cross-checked Codec 8 against Traccar's TeltonikaProtocolDecoder (no discrepancies)

26 new tests. Total 62 passing across 10 test files.
typecheck/lint/test/build all clean.
This commit is contained in:
Julian Çuni
2026-04-30 16:15:27 +02:00
parent 1e9219d14a
commit 381287bacc
34 changed files with 1672 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
test/fixtures/teltonika/README.md
Vendored
+79
View File
@@ -0,0 +1,79 @@
# Teltonika Fixture Suite
Binary protocol fixtures for the Codec 8, 8E, and 16 parsers.
## File format
Each fixture is a pair:
| File | Purpose |
|------|---------|
| `<name>.hex` | Hex-encoded AVL body (CodecID + N1 + records + N2) |
| `<name>.expected.json` | Expected `Position[]` output and ACK record count |
### .hex format
The body slice only — **not** the full TCP packet (no preamble, no DataFieldLength, no CRC).
This is exactly what `frame.payload` contains and what `handler.handle(body, ctx)` receives.
Whitespace and newlines are stripped before parsing, so you can write multi-line hex for readability.
### .expected.json format
```json
{
"positions": [
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:46.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 1,
"attributes": {
"21": 3,
"78": "__bigint:0",
"100": "__buffer_b64:AAEC"
}
}
],
"ack_record_count": 1
}
```
`device_id` is always `"FIXTURE"` — the IMEI comes from the session context, not the body.
#### Attribute value sentinels
| Sentinel | Decoded type | Example |
|---------|-------------|---------|
| number literal | `number` | `24079` |
| `"__bigint:<decimal>"` | `bigint` | `"__bigint:893700218"` |
| `"__buffer_b64:<base64>"` | `Buffer` | `"__buffer_b64:qw=="` |
For a zero-length Buffer, use `"__buffer_b64:"` (empty base64 string).
## How to add a new fixture
1. Get the AVL body bytes (from a live capture, a device emulator, or hand-computed).
2. Write the body as hex into `<name>.hex`.
3. Manually trace the expected parse output and write `<name>.expected.json`.
4. Run `pnpm test` — the new fixture is automatically discovered and tested.
No changes to any test file are needed.
## Bootstrap vs. synthetic fixtures
- **Bootstrap** fixtures (01-canonical, etc.) are sourced directly from the Teltonika documentation hex examples. Their expected outputs are read from the doc's parsed tables.
- **Synthetic** fixtures are hand-constructed for edge cases not covered by the canonical examples. Their expected outputs are computed manually and cross-checked.
## Cross-check methodology
Synthetic Codec 8 fixtures were cross-checked against the Traccar open-source
decoder (`TeltonikaProtocolDecoder.java`) for field widths and IO section parsing.
No discrepancies were found for the basic N1/N2/N4/N8 sections.
The NX section in Codec 8E has no equivalent in older Traccar versions; it was
verified by byte-level manual trace only.
test/fixtures/teltonika/codec16/01-canonical.expected.json
Vendored
+43
View File
@@ -0,0 +1,43 @@
{
"positions": [
{
"device_id": "FIXTURE",
"timestamp": "2019-07-10T12:06:54.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 0,
"attributes": {
"__event": 11,
"__generation_type": 5,
"1": 0,
"3": 0,
"11": 39,
"66": 22074
}
},
{
"device_id": "FIXTURE",
"timestamp": "2019-07-10T12:06:55.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 0,
"attributes": {
"__event": 11,
"__generation_type": 5,
"1": 0,
"3": 0,
"11": 38,
"66": 22074
}
}
],
"ack_record_count": 2
}
test/fixtures/teltonika/codec16/01-canonical.hex
Vendored
+1
View File
@@ -0,0 +1 @@
10020000016BDBC7833000000000000000000000000000000000000B05040200010000030002000B00270042563A00000000016BDBC7871800000000000000000000000000000000000B05040200010000030002000B00260042563A000002
test/fixtures/teltonika/codec16/02-each-generation-type.expected.json
Vendored
+61
View File
@@ -0,0 +1,61 @@
{
"positions": [
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:46.000Z",
"latitude": 0, "longitude": 0, "altitude": 0, "angle": 0, "speed": 0, "satellites": 0,
"priority": 1,
"attributes": { "__event": 10, "__generation_type": 0, "240": 0 }
},
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:47.000Z",
"latitude": 0, "longitude": 0, "altitude": 0, "angle": 0, "speed": 0, "satellites": 0,
"priority": 1,
"attributes": { "__event": 10, "__generation_type": 1, "240": 1 }
},
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:48.000Z",
"latitude": 0, "longitude": 0, "altitude": 0, "angle": 0, "speed": 0, "satellites": 0,
"priority": 1,
"attributes": { "__event": 10, "__generation_type": 2, "240": 2 }
},
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:49.000Z",
"latitude": 0, "longitude": 0, "altitude": 0, "angle": 0, "speed": 0, "satellites": 0,
"priority": 1,
"attributes": { "__event": 10, "__generation_type": 3, "240": 3 }
},
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:50.000Z",
"latitude": 0, "longitude": 0, "altitude": 0, "angle": 0, "speed": 0, "satellites": 0,
"priority": 1,
"attributes": { "__event": 10, "__generation_type": 4, "240": 4 }
},
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:51.000Z",
"latitude": 0, "longitude": 0, "altitude": 0, "angle": 0, "speed": 0, "satellites": 0,
"priority": 1,
"attributes": { "__event": 10, "__generation_type": 5, "240": 5 }
},
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:52.000Z",
"latitude": 0, "longitude": 0, "altitude": 0, "angle": 0, "speed": 0, "satellites": 0,
"priority": 1,
"attributes": { "__event": 10, "__generation_type": 6, "240": 6 }
},
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:53.000Z",
"latitude": 0, "longitude": 0, "altitude": 0, "angle": 0, "speed": 0, "satellites": 0,
"priority": 1,
"attributes": { "__event": 10, "__generation_type": 7, "240": 7 }
}
],
"ack_record_count": 8
}
test/fixtures/teltonika/codec16/02-each-generation-type.hex
Vendored
+1
View File
@@ -0,0 +1 @@
10080000016B40D8EA3001000000000000000000000000000000000A00010100F0000000000000016B40D8EE1801000000000000000000000000000000000A01010100F0010000000000016B40D8F20001000000000000000000000000000000000A02010100F0020000000000016B40D8F5E801000000000000000000000000000000000A03010100F0030000000000016B40D8F9D001000000000000000000000000000000000A04010100F0040000000000016B40D8FDB801000000000000000000000000000000000A05010100F0050000000000016B40D901A001000000000000000000000000000000000A06010100F0060000000000016B40D9058801000000000000000000000000000000000A07010100F00700000008
test/fixtures/teltonika/codec16/03-large-io-id.expected.json
Vendored
+21
View File
@@ -0,0 +1,21 @@
{
"positions": [
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:46.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 1,
"attributes": {
"__event": 1024,
"__generation_type": 5,
"1024": 255
}
}
],
"ack_record_count": 1
}
test/fixtures/teltonika/codec16/03-large-io-id.hex
Vendored
+1
View File
@@ -0,0 +1 @@
10010000016B40D8EA300100000000000000000000000000000004000501010400FF00000001
test/fixtures/teltonika/codec8/01-single-record-all-widths.expected.json
Vendored
+24
View File
@@ -0,0 +1,24 @@
{
"positions": [
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:46.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 1,
"attributes": {
"__event": 1,
"21": 3,
"1": 1,
"66": 24079,
"241": 24602,
"78": "__bigint:0"
}
}
],
"ack_record_count": 1
}
test/fixtures/teltonika/codec8/01-single-record-all-widths.hex
Vendored
+1
View File
@@ -0,0 +1 @@
08010000016B40D8EA30010000000000000000000000000000000105021503010101425E0F01F10000601A014E000000000000000001
test/fixtures/teltonika/codec8/02-single-record-reduced.expected.json
Vendored
+22
View File
@@ -0,0 +1,22 @@
{
"positions": [
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:05:36.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 1,
"attributes": {
"__event": 1,
"21": 3,
"1": 1,
"66": 24080
}
}
],
"ack_record_count": 1
}
test/fixtures/teltonika/codec8/02-single-record-reduced.hex
Vendored
+1
View File
@@ -0,0 +1 @@
08010000016B40D9AD80010000000000000000000000000000000103021503010101425E10000001
test/fixtures/teltonika/codec8/03-two-records.expected.json
Vendored
+35
View File
@@ -0,0 +1,35 @@
{
"positions": [
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:01:01.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 1,
"attributes": {
"__event": 1,
"1": 0
}
},
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:01:19.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 1,
"attributes": {
"__event": 1,
"1": 1
}
}
],
"ack_record_count": 2
}
test/fixtures/teltonika/codec8/03-two-records.hex
Vendored
+1
View File
@@ -0,0 +1 @@
08020000016B40D57B480100000000000000000000000000000001010101000000000000016B40D5C19801000000000000000000000000000000010101010100000002
test/fixtures/teltonika/codec8/04-empty-io-bag.expected.json
Vendored
+19
View File
@@ -0,0 +1,19 @@
{
"positions": [
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:46.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 0,
"attributes": {
"__event": 0
}
}
],
"ack_record_count": 1
}
test/fixtures/teltonika/codec8/04-empty-io-bag.hex
Vendored
+1
View File
@@ -0,0 +1 @@
08010000016B40D8EA300000000000000000000000000000000000000000000001
test/fixtures/teltonika/codec8/05-multi-record-large.expected.json
Vendored
+125
View File
@@ -0,0 +1,125 @@
{
"positions": [
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:46.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 1,
"attributes": { "__event": 1, "1": 0 }
},
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:47.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 1,
"attributes": { "__event": 1, "1": 1 }
},
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:48.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 1,
"attributes": { "__event": 1, "1": 2 }
},
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:49.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 1,
"attributes": { "__event": 1, "1": 3 }
},
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:50.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 1,
"attributes": { "__event": 1, "1": 4 }
},
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:51.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 1,
"attributes": { "__event": 1, "1": 5 }
},
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:52.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 1,
"attributes": { "__event": 1, "1": 6 }
},
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:53.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 1,
"attributes": { "__event": 1, "1": 7 }
},
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:54.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 1,
"attributes": { "__event": 1, "1": 8 }
},
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:55.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 1,
"attributes": { "__event": 1, "1": 9 }
}
],
"ack_record_count": 10
}
test/fixtures/teltonika/codec8/05-multi-record-large.hex
Vendored
+1
View File
@@ -0,0 +1 @@
080A0000016B40D8EA300100000000000000000000000000000001010101000000000000016B40D8EE180100000000000000000000000000000001010101010000000000016B40D8F2000100000000000000000000000000000001010101020000000000016B40D8F5E80100000000000000000000000000000001010101030000000000016B40D8F9D00100000000000000000000000000000001010101040000000000016B40D8FDB80100000000000000000000000000000001010101050000000000016B40D901A00100000000000000000000000000000001010101060000000000016B40D905880100000000000000000000000000000001010101070000000000016B40D909700100000000000000000000000000000001010101080000000000016B40D90D580100000000000000000000000000000001010101090000000A
test/fixtures/teltonika/codec8e/01-canonical.expected.json
Vendored
+24
View File
@@ -0,0 +1,24 @@
{
"positions": [
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T11:36:32.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 1,
"attributes": {
"__event": 1,
"1": 1,
"17": 29,
"16": 22949000,
"11": "__bigint:893700218",
"14": "__bigint:500686954"
}
}
],
"ack_record_count": 1
}
test/fixtures/teltonika/codec8e/01-canonical.hex
Vendored
+1
View File
@@ -0,0 +1 @@
8E010000016B412CEE000100000000000000000000000000000000010005000100010100010011001D00010010015E2C880002000B000000003544C87A000E000000001DD7E06A000001
test/fixtures/teltonika/codec8e/02-nx-mixed.expected.json
Vendored
+22
View File
@@ -0,0 +1,22 @@
{
"positions": [
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:46.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 1,
"attributes": {
"__event": 0,
"1": "__buffer_b64:qw==",
"2": "__buffer_b64:3q2+7wECAwQ=",
"3": "__buffer_b64:YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXp7fH1+f4CBgoOEhYaHiImKi4yNjo+QkZKTlJWWl5iZmpucnZ6foA=="
}
}
],
"ack_record_count": 1
}
test/fixtures/teltonika/codec8e/02-nx-mixed.hex
Vendored
+1
View File
@@ -0,0 +1 @@
8E010000016B40D8EA3001000000000000000000000000000000000000030000000000000000000300010001AB00020008DEADBEEF01020304000300406162636465666768696A6B6C6D6E6F707172737475767778797A7B7C7D7E7F808182838485868788898A8B8C8D8E8F909192939495969798999A9B9C9D9E9FA001
test/fixtures/teltonika/codec8e/03-nx-zero-length.expected.json
Vendored
+20
View File
@@ -0,0 +1,20 @@
{
"positions": [
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:46.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 0,
"attributes": {
"__event": 0,
"5": "__buffer_b64:"
}
}
],
"ack_record_count": 1
}
test/fixtures/teltonika/codec8e/03-nx-zero-length.hex
Vendored
+1
View File
@@ -0,0 +1 @@
8E010000016B40D8EA300000000000000000000000000000000000000001000000000000000000010005000001
test/fixtures/teltonika/codec8e/04-nx-large-length.expected.json
Vendored
+20
View File
@@ -0,0 +1,20 @@
{
"positions": [
{
"device_id": "FIXTURE",
"timestamp": "2019-06-10T10:04:46.000Z",
"latitude": 0,
"longitude": 0,
"altitude": 0,
"angle": 0,
"speed": 0,
"satellites": 0,
"priority": 0,
"attributes": {
"__event": 0,
"7": "__buffer_b64:AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6e3x9fn+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX2Nna29zd3t/g4eLj5OXm5+jp6uvs7e7v8PHy8/T19vf4+fr7/P3+/wABAgMEBQYHCAkKCwwNDg8QERITFBUWFxgZGhscHR4fICEiIyQlJicoKSor"
}
}
],
"ack_record_count": 1
}
test/fixtures/teltonika/codec8e/04-nx-large-length.hex
Vendored
+1
View File
@@ -0,0 +1 @@
8E010000016B40D8EA300000000000000000000000000000000000000001000000000000000000010007012C000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F202122232425262728292A2B2C2D2E2F303132333435363738393A3B3C3D3E3F404142434445464748494A4B4C4D4E4F505152535455565758595A5B5C5D5E5F606162636465666768696A6B6C6D6E6F707172737475767778797A7B7C7D7E7F808182838485868788898A8B8C8D8E8F909192939495969798999A9B9C9D9E9FA0A1A2A3A4A5A6A7A8A9AAABACADAEAFB0B1B2B3B4B5B6B7B8B9BABBBCBDBEBFC0C1C2C3C4C5C6C7C8C9CACBCCCDCECFD0D1D2D3D4D5D6D7D8D9DADBDCDDDEDFE0E1E2E3E4E5E6E7E8E9EAEBECEDEEEFF0F1F2F3F4F5F6F7F8F9FAFBFCFDFEFF000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F202122232425262728292A2B01