[FL-3041] IR format docs (#2162)

Co-authored-by: あく <alleteam@gmail.com>
2022-12-20 18:07:19 +03:00 · 2022-12-20 18:07:19 +03:00 · c34ae66b6e
commit c34ae66b6e
parent e0d716647c
1 changed files with 111 additions and 0 deletions
--- a/documentation/file_formats/InfraredFileFormats.md
+++ b/documentation/file_formats/InfraredFileFormats.md
@ -0,0 +1,111 @@
+# Infrared Flipper File Formats
+
+## Infrared Remote File Format
+### Example
+
+    Filetype: IR signals file
+    Version: 1
+    # 
+    name: Button_1
+    type: parsed
+    protocol: NECext
+    address: EE 87 00 00
+    command: 5D A0 00 00
+    #
+    name: Button_2
+    type: raw
+    frequency: 38000
+    duty_cycle: 0.330000
+    data: 504 3432 502 483 500 484 510 502 502 482 501 485 509 1452 504 1458 509 1452 504 481 501 474 509 3420 503
+    #
+    name: Button_3
+    type: parsed
+    protocol: SIRC
+    address: 01 00 00 00
+    command: 15 00 00 00
+
+### Description
+Filename extension: `.ir`
+
+This file format is used to store an infrared remote that consists of an arbitrary number of buttons. 
+Each button is separated from others by a comment character (`#`) for better readability.
+
+Known protocols are represented in the `parsed` form, whereas non-recognised signals may be saved and re-transmitted as `raw` data.
+
+#### Version history:
+1. Initial version.
+
+#### Format fields
+| Name       | Use     | Type   | Description |
+| ---------- | ------- | ------ |------------ |
+| name       | both    | string | Name of the button. Only printable ASCII characters are allowed. |
+| type       | both    | string | Type of the signal. Must be `parsed` or `raw`.  |
+| protocol   | parsed  | string | Name of the infrared protocol. Refer to `ir` console command for the complete list of supported protocols. |
+| address    | parsed  | hex    | Payload address. Must be 4 bytes long. |
+| command    | parsed  | hex    | Payload command. Must be 4 bytes long. |
+| frequency  | raw     | uint32 | Carrier frequency, in Hertz, usually 38000 Hz. |
+| duty_cycle | raw     | float  | Carrier duty cycle, usually 0.33. |
+| data       | raw     | uint32 | Raw signal timings, in microseconds between logic level changes. Individual elements must be space-separated. Maximum timings amount is 1024. |
+
+## Infrared Library File Format
+### Examples
+- [TV Universal Library](/assets/resources/infrared/assets/tv.ir)
+- [A/C Universal Library](/assets/resources/infrared/assets/ac.ir)
+- [Audio Universal Library](/assets/resources/infrared/assets/audio.ir)
+
+### Description
+Filename extension: `.ir`
+
+This file format is used to store universal remote libraries. It is identical to the previous format, differing only in the `Filetype` field.\
+It also has predefined button names for each universal library type, so that the universal remote application could understand them.
+See [Universal Remotes](/documentation/UniversalRemotes.md) for more information.
+
+### Version history:
+1. Initial version.
+
+## Infrared Test File Format
+### Examples
+See [Infrared Unit Tests](/assets/unit_tests/infrared/) for various examples.
+### Description
+Filename extension: `.irtest`
+
+This file format is used to store technical test data that is too large to keep directly in the firmware.
+It is mostly similar to the two previous formats, with the main difference being the addition of the parsed signal arrays.
+
+Each infrared protocol must have corresponding unit tests complete with an `.irtest` file.
+
+Known protocols are represented in the `parsed_array` form, whereas raw data has the `raw` type.\
+Note: a single parsed signal must be represented as an array of size 1.
+
+### Version history:
+1. Initial version.
+
+#### Format fields
+| Name       | Use          | Type   | Description |
+| ---------- | ------------ | ------ |------------ |
+| name       | both         | string | Name of the signal. Only printable ASCII characters are allowed. |
+| type       | both         | string | Type of the signal. Must be `parsed_array` or `raw`.  |
+| count      | parsed_array | uint32 | The number of parsed signals in an array. Must be at least 1. |
+| protocol   | parsed_array | string | Same as in previous formats. |
+| address    | parsed_array | hex    | Ditto. |
+| command    | parsed_array | hex    | Ditto. |
+| repeat     | parsed_array | bool   | Indicates whether the signal is a repeated button press. |
+| frequency  | raw          | uint32 | Same as in previous formats. |
+| duty_cycle | raw          | float  | Ditto. |
+| data       | raw          | uint32 | Ditto. |
+
+#### Signal names
+The signal names in an `.irtest` file folow a convention `<name><test_number>`, where the name is one of:
+- decoder_input
+- decoder_expected
+- encoder_decoder_input,
+
+and the number is a sequential integer: 1, 2, 3...etc, which produces names like `decoder_input1`, `encoder_decoder_input3`, and so on.
+
+| Name                  | Type         | Description |
+| --------------------- | ------------ | ----------- |
+| decoder_input         | raw          | A raw signal contaning the decoder input. Is also used as the expected encoder output. |
+| decoder_expected      | parsed_array | An array of parsed signals containing the expected decoder output. Is also used as the encoder input. |
+| encoder_decoder_input | parsed_array | An array of parsed signals containing both the encoder-decoder input and expected output. |
+
+See [Unit Tests](/documentation/UnitTests.md#infrared) for more info.