{"id":12984,"library":"complete-teltonika-parser","title":"Complete Teltonika Parser","description":"The `complete-teltonika-parser` library, currently at version 0.3.6, provides robust parsing capabilities for various Teltonika communication protocols, specifically focusing on AVL data ('data sending') and GPRS messages. It differentiates itself by handling the complexities of Teltonika codecs, such as Codec 12 for GPRS messages, and includes a separate utility function, `parseIMEI`, for device identification packets. A key feature is its careful handling of large numeric values within `IOelement.Elements`, converting them to strings (via `BigInt`) when they exceed JavaScript's `Number.MAX_SAFE_INTEGER` to prevent data loss. The library also ships with TypeScript types, enhancing developer experience by providing strong type checking for the parsed data structures. While no explicit release cadence is stated, updates are typically driven by new Teltonika codec specifications or community contributions.","status":"active","version":"0.3.6","language":"javascript","source_language":"en","source_url":"https://github.com/TimeLord2010/TeltonikaParser","tags":["javascript","teltonika","teltonika-parser","typescript"],"install":[{"cmd":"npm install complete-teltonika-parser","lang":"bash","label":"npm"},{"cmd":"yarn add complete-teltonika-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add complete-teltonika-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While the README uses CommonJS `require`, ESM `import` is the standard for modern JavaScript/TypeScript.","wrong":"const { ProtocolParser } = require('complete-teltonika-parser')","symbol":"ProtocolParser","correct":"import { ProtocolParser } from 'complete-teltonika-parser'"},{"note":"Used for parsing IMEI packets, separate from the main ProtocolParser class.","wrong":"const { parseIMEI } = require('complete-teltonika-parser')","symbol":"parseIMEI","correct":"import { parseIMEI } from 'complete-teltonika-parser'"},{"note":"Imports `Data` as a type for static analysis. It's also exported at runtime, but typically consumed as a type.","wrong":"import { Data } from 'complete-teltonika-parser'","symbol":"Data","correct":"import type { Data } from 'complete-teltonika-parser'"},{"note":"Imports `IOelement` as a type for static analysis, providing structure for parsed I/O data.","symbol":"IOelement","correct":"import type { IOelement } from 'complete-teltonika-parser'"}],"quickstart":{"code":"import { ProtocolParser, parseIMEI } from 'complete-teltonika-parser';\n\n// Example Teltonika data packet (hex string)\nconst dataPacket = '00000000000000fd8e0100000176169220e000067673631b1ab6be008f00000f000000000031001800010000020000030100040000b30000b40000320000330000160400470300f00000150300c80000ef00009001004fff0051ff0052ff0053ff0055ff006e01007aff007fff286cff000d00090028000a0036000b003500f50027004327540044000000425c80001800000046009500ecfffd00edffe500ee03d00080ffff00080050ffffffff0054ffffffff0056ffffffff0057ffffffff0058ffffffff0068ffffffff0071ffffffff0087ffffffff000400da0000d546ca81f6ac00db383934343530323700dc303631393934313900dd3332320000000000000001000089fb';\n\n// Example Teltonika IMEI packet (hex string)\nconst imeiPacket = '000F333532303933303839313638383231';\n\n// Function to determine packet type and parse accordingly\nfunction processPacket(packet: string) {\n    if (packet.length === 34) { // IMEI packets have a constant length of 34 characters (17 bytes hex)\n        console.log('Detected IMEI packet.');\n        return {\n            imei: parseIMEI(packet)\n        };\n    } else {\n        console.log('Detected data packet.');\n        const parsed = new ProtocolParser(packet);\n        // Type narrowing based on CodecType property\n        if (parsed.CodecType === \"data sending\") {\n            console.log('Parsed AVL data:', (parsed.Content as typeof parsed.Content).AVL_Datas[0]);\n        } else if (parsed.CodecType === \"GPRS messages\") {\n            console.log('Parsed GPRS message:', parsed.Content);\n        }\n        return {\n            dataPacket: parsed\n        };\n    }\n}\n\n// Process the example data packet\nconst dataResult = processPacket(dataPacket);\nconsole.log('Data parsing result:', dataResult.dataPacket?.Content?.['AVL_Datas']?.[0]?.GPSelement);\n\n// Process the example IMEI packet\nconst imeiResult = processPacket(imeiPacket);\nconsole.log('IMEI parsing result:', imeiResult.imei);\n\n// Demonstrating large number handling (conceptual, not from live packet)\n// In a real scenario, you'd check IOelement.Elements values directly.\nconst exampleIOelement = {\n    EventID: 1,\n    ElementCount: 1,\n    Elements: {\n        1000: 'FFFFFFFFFFFFFFFF' // Represents a very large number\n    }\n};\n\nconst largeValueHex = exampleIOelement.Elements[1000] as string;\nlet largeValue: number | string = parseInt(largeValueHex, 16);\nif (largeValue > Number.MAX_SAFE_INTEGER) {\n  largeValue = BigInt(`0x${largeValueHex}`).toString();\n}\nconsole.log('Example of large IO element value:', largeValue);","lang":"typescript","description":"This quickstart demonstrates how to use `ProtocolParser` for Teltonika data packets and `parseIMEI` for IMEI packets, including a common pattern for distinguishing between the two packet types based on length. It also illustrates how large numbers within IO elements are handled as strings."},"warnings":[{"fix":"Wrap `new ProtocolParser()` calls in a try-catch block to gracefully handle `Error` exceptions related to invalid CRC. Consider logging the malformed packet for debugging.","message":"The parser will throw an exception if the data packet has an invalid CRC. Implement robust error handling (e.g., try-catch blocks) around parsing operations.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Verify that your Teltonika devices are configured to use Codec 12 for GPRS messages if you intend to parse them with this library. For other codecs, consider alternative parsers or contributing to this library.","message":"Only GPRS Codec 12 is currently supported for GPRS messages. Attempting to parse packets using other GPRS codecs may result in incorrect data or parsing failures.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Always check the type of `IOelement.Elements` values. If a `string`, parse it as `BigInt` if arithmetic is needed, or handle it as a string. Avoid `parseInt()` alone for these values without prior BigInt conversion if precision beyond `Number.MAX_SAFE_INTEGER` is critical.","message":"Values in `IOelement.Elements` that are too large to fit into JavaScript's `Number.MAX_SAFE_INTEGER` will be returned as strings (representing a BigInt). Direct numeric operations on these values will require careful handling or conversion.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Always use the dedicated `parseIMEI` function for packets identified as IMEI. A common pattern is to check packet length (IMEI packets are often fixed length, e.g., 34 hex characters) before deciding which parser to use.","message":"The `ProtocolParser` is designed solely for parsing Teltonika protocol data (AVL, GPRS messages), not the device IMEI. Using it for IMEI packets will lead to parsing errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure `basic_read` is `false` if you need the `Content` to be fully parsed. If `basic_read` is `true`, always check `parsed.Content !== null` before attempting to access properties like `parsed.Content.AVL_Datas`.","message":"The `ProtocolParser` constructor accepts an optional `basic_read: boolean` parameter. If `true`, the `Content` property of the parsed object will be `null`, which can cause runtime `TypeError` if accessed without a null check.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure all input data is converted to a hexadecimal string representation before passing it to the parser functions. For example, `Buffer.from('...', 'hex').toString('hex')` or similar pre-processing.","message":"The library expects all input packets (for both `ProtocolParser` and `parseIMEI`) to be raw hexadecimal strings. Providing inputs in other formats (e.g., binary buffers, UTF-8 strings) will lead to parsing errors.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Wrap `new ProtocolParser()` calls in a try-catch block. Log the erroneous packet for analysis. The device might be sending corrupted data, or there's network noise. You might consider ignoring the packet or requesting retransmission if your setup allows.","cause":"The received Teltonika data packet failed its Cyclic Redundancy Check (CRC) validation, indicating data corruption.","error":"Error: Invalid CRC"},{"fix":"Convert your input data to a hexadecimal string before passing it to the parser. For example, if you receive a Node.js `Buffer`, use `buffer.toString('hex')`.","cause":"The input `packet` provided to `ProtocolParser` or `parseIMEI` is not a string, but likely a `Buffer` or other object.","error":"TypeError: packet.slice is not a function"},{"fix":"This typically occurs if `new ProtocolParser(packet, true)` (with `basic_read: true`) was used. Ensure `basic_read` is `false` if full content parsing is desired, or add a null check: `if (parsed.Content && parsed.CodecType === \"data sending\") { /* access AVL_Datas */ }`.","cause":"Attempting to access `parsed.Content.AVL_Datas` when `parsed.Content` is `null`.","error":"TypeError: Cannot read properties of null (reading 'AVL_Datas')"},{"fix":"Validate the input string's length and character set before calling `parseIMEI`. Ensure it's a pure hexadecimal string of the correct length for Teltonika IMEI packets.","cause":"The string provided to `parseIMEI` does not conform to the expected length (e.g., 34 characters for a 17-byte hex IMEI) or contains non-hexadecimal characters.","error":"IMEI parsing error: Invalid length or format"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}