diff --git a/docs/TTN_decoder.md b/docs/TTN_decoder.md new file mode 100644 index 0000000..869f874 --- /dev/null +++ b/docs/TTN_decoder.md @@ -0,0 +1,71 @@ +# TTN-Decoder Documentation + +***Repository of the decoder V1***: +[v1.0 Decoder of the CayenneLPP - JavaScript TheThingsNetwork](https://github.com/HAN-IoT-LAB/TTN-Decoder) + +The TTN-Decoder is a JavaScript-based implementation designed to decode payloads encoded using the Cayenne Low Power Payload (CayenneLPP) format. Developed with a focus on memory optimization and refactorization, this decoder operates within TheThingsNetwork (TTN), making it an ideal solution for a variety of web-based applications, user interfaces, or dashboards aimed at generic IoT applications. + +## Features + +The decoder boasts a comprehensive range of features designed to support a wide variety of sensor data, ensuring versatility for applications such as data loggers, telemetry systems, or device remote-monitoring. Key features include: + +- **Wide Range of Sensor Support**: Capable of decoding data from a diverse array of sensors including digital inputs/outputs, analog inputs, illumination, presence, temperature, humidity, accelerometers, barometers, gyroscopes, and GPS location. +- **High Precision (Configurable)**: Features precision scaling to ensure accurate data interpretation, essential for GPS coordinates and altitude measurements. +- **Endian-Aware Processing**: Guarantees the correct handling of byte order, crucial for the accurate interpretation of multi-byte sensor data. +- **Comprehensive Unit Testing**: Ensures decoder reliability and quality, with tests conducted using the Jest Framework. + +## Design Overview + +The decoder's design revolves around a consistent payload structure, where the DataType is critical for establishing expectations regarding datasize, precision, signedness, and unit representation. + +### Payload Structure + +Encoded and decoded payloads adhere to a uniform structure outlined as follows: + +``` +[Sensor Type] [Channel] [Data Bytes...] +``` + +This structure ensures seamless encoding and decoding processes, with each component playing a vital role in data interpretation. + +### Sensor Data Types + +Each sensor data type directly correlates with the encoder's format, adhering to the IPSO Alliance Smart Objects Guidelines for standardized Object IDs. The conversion to fit the Object ID into a single byte is as shown below: + +``` +LPP_DATA_TYPE = IPSO_OBJECT_ID - 3200 +``` + +A table detailing the supported sensor types, their corresponding type IDs, precision levels, signedness, and byte lengths is provided to clarify the data types recognized by the decoder. + +## Getting Started + +The decoder is primarily utilized on TheThingsNetwork but can also run natively for development or testing purposes. + +### Prerequisites + +- **NodeJS**: Required for native execution on personal devices. +- **Jest**: Necessary for running unit tests, installable via npm. +- **TheThingsNetwork Application**: Essential for deployment or testing with target devices. + +## Testing + +Testing is a crucial aspect of the decoder's development, ensuring accurate sensor data decoding. An overview of test scenarios is provided, highlighting the expected outcomes for each sensor type. + +### Running Unit Tests + +To execute the unit tests: + +```bash +npm test +``` + +This command triggers the Jest-based tests, verifying the decoder's functionality across various scenarios. + +## License + +The TTN-Decoder is released under the Creative Commons Attribution-NonCommercial 4.0 International License, permitting redistribution and modification for non-commercial purposes. This initiative is a collaborative effort by Richard Kroesen, Klaasjan Wagenaar, and Tristan Bosveld. + +![Creative Commons License](https://i.creativecommons.org/l/by-nc/4.0/88x31.png) + +This work is licensed under a [Creative Commons Attribution-NonCommercial 4.0 International License](http://creativecommons.org/licenses/by-nc/4.0/). \ No newline at end of file diff --git a/docs/Unit_tests_overview.md b/docs/Unit_tests_overview.md new file mode 100644 index 0000000..885b0d1 --- /dev/null +++ b/docs/Unit_tests_overview.md @@ -0,0 +1,29 @@ + +In the table presented below, we offer a comprehensive overview of the unit tests conducted on the refactored CayenneLPP library. These tests are crucial for validating the functionality and reliability of the library across various scenarios. The unit tests have been meticulously crafted using the Unity Framework. Unity provides a straightforward approach to writing and running tests, making it an ideal choice for our library's validation process. + +The design of our tests is heavily influenced by the AAA (Arrange, Act, Assert) methodology, a standard structure that promotes clarity and maintainability in test writing. + +The focus of these tests is primarily on input and output validation, ensuring that for given inputs, the library produces expected outputs without errors. This includes testing for correct payload encoding based on sensor data, verifying the integrity of encoded data, and ensuring that the library behaves as intended across a wide range of input values. + +All tests are ran natively for development convenience. + +| Test Function | Description | Expected Outcome | +|--------------------------------|----------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------| +| `test_addDigitalInput` | Tests adding a digital input to the payload. | Non-zero result; buffer contains correct data type, channel, and value; size is 3. | +| `test_addDigitalOutput` | Tests adding a digital output to the payload. | Non-zero result; buffer contains correct data type, channel, and value; value matches provided input. | +| `test_addDigitalOutput_bool` | Tests adding a boolean digital output to the payload. | Non-zero result; buffer contains correct data type, channel, and boolean value as true. | +| `test_addAnalogInput` | Tests adding an analog input with a floating-point value to the payload. | Non-zero result; buffer contains correct data type, channel, and scaled value; size is accurate. | +| `test_addAnalogOutput` | Tests adding an analog output to the payload. | Non-zero result; buffer contains correct data type, channel, and value as scaled integer. | +| `test_addIllumination` | Tests adding an illumination value to the payload. | Non-zero result; buffer correctly represents illumination sensor data with little endian conversion. | +| `test_addPresence` | Tests adding a presence detection value to the payload. | Non-zero result; buffer contains correct presence data. | +| `test_addTemperature` | Tests adding a temperature value to the payload. | Non-zero result; buffer contains correct temperature data; size matches expectation. | +| `test_addHumidity` | Tests adding a humidity value to the payload. | Non-zero result; buffer represents humidity correctly in 0.5% increments. | +| `test_addAccelerometer` | Tests adding accelerometer data (x, y, z) to the payload. | Non-zero result; buffer accurately represents accelerometer data; correct data size. | +| `test_addBarometer` | Tests adding barometric pressure to the payload. | Non-zero result; buffer accurately represents barometric data; correct endianess and data size. | +| `test_addGyroscope` | Tests adding gyroscope data (x, y, z) to the payload. | Non-zero result; buffer accurately represents gyroscope data; correct data size. | +| `test_addGPSLocation` | Tests adding GPS location data (lat, lon, alt) to the payload. | Non-zero result; buffer accurately represents GPS location data; correct data size. | +| `test_CayenneLPP_CopyAssignment` | Tests the copy assignment operator for `CayenneLPP` objects. | Copied object's buffer matches source; correct size. | +| `test_CopyToValidBuffer` | Tests copying payload data to a provided buffer. | Copied bytes match expected number; destination buffer matches source payload. | +| `test_CopyToNullBuffer` | Tests behavior when attempting to copy payload data to a `nullptr` buffer. | Copied bytes are 0; function handles `nullptr` gracefully. | + +## Result: PASSED \ No newline at end of file diff --git a/images/LORAWAN.png b/images/LORAWAN.png new file mode 100644 index 0000000..86e651a Binary files /dev/null and b/images/LORAWAN.png differ diff --git a/images/LoRaWAN_Logo_DALLE.ico b/images/LoRaWAN_Logo_DALLE.ico deleted file mode 100644 index b5fbfa6..0000000 Binary files a/images/LoRaWAN_Logo_DALLE.ico and /dev/null differ diff --git a/mkdocs.yml b/mkdocs.yml index 2e68a52..44193aa 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,8 +2,6 @@ site_name: HAN-IoT-LAB2324 | LoRaWAN Payload Encoder theme: name: material - logo: images/logo.png - favicon: images/LoRaWAN_Logo_DALLE.ico palette: primary: 'blue grey' accent: 'orange' @@ -15,7 +13,9 @@ plugins: - mkdoxy: projects: Doxygen: - src-dirs: include/ + src-dirs: + include/ + test/ full-doc: True doxy-cfg: FILE_PATTERNS: "*.cpp *.hpp" @@ -29,6 +29,11 @@ nav: - 'Classes': 'Doxygen/classes.md' - 'Hierarchy': 'Doxygen/hierarchy.md' - 'Files': 'Doxygen/files.md' - + - header: Doxygen\_cayenne_l_p_p_8hpp.md + - src: Doxygen\_cayenne_l_p_p_8hpp_source.md + - header types: Doxygen\_cayenne_references_8hpp.md + - src types: Doxygen\_cayenne_references_8hpp_source.md + - Unit Testing: Unit_tests_overview.md + - Decoder: TTN_decoder.md copyright: Copyright (c) 2024 March by Klaasjan Wagenaar, Tristan Bosveld and Richard Kroesen \ No newline at end of file