├── .gitignore ├── Flow.md ├── LICENSE ├── RCPSpecification.md ├── RCPValue.md ├── RCPWidget.md ├── RCP_diagram.svg ├── README.md ├── example_data ├── multi_packet_s8-broken2.rcp ├── multi_packet_s8.rcp ├── packet_bool_no_user.rcp ├── packet_bool_userdata.rcp ├── packet_enum.rcp ├── packet_info.rcp ├── packet_info_nodata.rcp ├── packet_initialize.rcp ├── packet_initialize_id_data.rcp ├── packet_lstr_no_user.rcp ├── packet_range.rcp ├── packet_remove.rcp ├── packet_s16_no_user.rcp ├── packet_s32_no_user.rcp ├── packet_s8_no_user.rcp ├── packet_string_default.rcp ├── packet_u16_no_user.rcp ├── packet_u32_no_user.rcp ├── packet_u8_no_user.rcp ├── packet_update_array_int8.rcp ├── packet_update_bool.rcp ├── packet_update_boolarray_no_user.rcp ├── packet_update_i16.rcp ├── packet_update_i32.rcp ├── packet_update_i8.rcp ├── packet_update_u16.rcp ├── packet_update_u32.rcp ├── packet_update_u8.rcp ├── packet_updatevalue_s16.rcp ├── packet_updatevalue_s32.rcp ├── packet_updatevalue_s8.rcp ├── packet_updatevalue_string.rcp ├── packet_updatevalue_u16.rcp ├── packet_updatevalue_u32.rcp ├── packet_updatevalue_u8.rcp ├── packet_uri.rcp └── parameter_s8_no_user.rcp └── kaitai └── RCPTypes.ksy /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store -------------------------------------------------------------------------------- /Flow.md: -------------------------------------------------------------------------------- 1 | # Protocol Flow 2 | 3 | ## Version Handshake 4 | 5 | 1. Client sends a info-packet 6 | 1. Server receives info-packet 7 | 1. Server sends info-packet to client 8 | 1. Server checks if its runtime-version is between client rcp-version and base-version (inclusive) 9 | 1. Version ok -> wait for [Initialization](#Initialization) 10 | 1. Version mismatch: 11 | 1. Server is strict -> close connection 12 | 1. Server not strict -> wait for [Initialization](#Initialization) 13 | 1. Client receives info: 14 | 1. Version ok: [Initialization](#Initialization) 15 | 1. Version missmatch: 16 | 1. Decide to close connection 17 | 1. Or client sends initialize and skip packages if a parsing error occurs due to unknown options. See: [Initialization](#Initialization) 18 | 19 | ## Initialization 20 | 21 | 6. A client sends an initialize-packet with a value of 0 to request all parameters from the server 22 | 6. The server answers with a initialize-packet containing the number of parameters it will send (This allows a client to draw a progress-bar while receiving the initial set of parameters.) 23 | 6. The server sends update packets with all the requested parameters 24 | 6. After receiving all parameters the client is fully initialized 25 | 26 | ## Update 27 | 28 | 10. Server and clients send update or update-value packets 29 | 10. Servers may also remove Parameters with a remove-packet 30 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | GNU LESSER GENERAL PUBLIC LICENSE 2 | Version 3, 29 June 2007 3 | 4 | Copyright (C) 2007 Free Software Foundation, Inc. 5 | Everyone is permitted to copy and distribute verbatim copies 6 | of this license document, but changing it is not allowed. 7 | 8 | 9 | This version of the GNU Lesser General Public License incorporates 10 | the terms and conditions of version 3 of the GNU General Public 11 | License, supplemented by the additional permissions listed below. 12 | 13 | 0. Additional Definitions. 14 | 15 | As used herein, "this License" refers to version 3 of the GNU Lesser 16 | General Public License, and the "GNU GPL" refers to version 3 of the GNU 17 | General Public License. 18 | 19 | "The Library" refers to a covered work governed by this License, 20 | other than an Application or a Combined Work as defined below. 21 | 22 | An "Application" is any work that makes use of an interface provided 23 | by the Library, but which is not otherwise based on the Library. 24 | Defining a subclass of a class defined by the Library is deemed a mode 25 | of using an interface provided by the Library. 26 | 27 | A "Combined Work" is a work produced by combining or linking an 28 | Application with the Library. The particular version of the Library 29 | with which the Combined Work was made is also called the "Linked 30 | Version". 31 | 32 | The "Minimal Corresponding Source" for a Combined Work means the 33 | Corresponding Source for the Combined Work, excluding any source code 34 | for portions of the Combined Work that, considered in isolation, are 35 | based on the Application, and not on the Linked Version. 36 | 37 | The "Corresponding Application Code" for a Combined Work means the 38 | object code and/or source code for the Application, including any data 39 | and utility programs needed for reproducing the Combined Work from the 40 | Application, but excluding the System Libraries of the Combined Work. 41 | 42 | 1. Exception to Section 3 of the GNU GPL. 43 | 44 | You may convey a covered work under sections 3 and 4 of this License 45 | without being bound by section 3 of the GNU GPL. 46 | 47 | 2. Conveying Modified Versions. 48 | 49 | If you modify a copy of the Library, and, in your modifications, a 50 | facility refers to a function or data to be supplied by an Application 51 | that uses the facility (other than as an argument passed when the 52 | facility is invoked), then you may convey a copy of the modified 53 | version: 54 | 55 | a) under this License, provided that you make a good faith effort to 56 | ensure that, in the event an Application does not supply the 57 | function or data, the facility still operates, and performs 58 | whatever part of its purpose remains meaningful, or 59 | 60 | b) under the GNU GPL, with none of the additional permissions of 61 | this License applicable to that copy. 62 | 63 | 3. Object Code Incorporating Material from Library Header Files. 64 | 65 | The object code form of an Application may incorporate material from 66 | a header file that is part of the Library. You may convey such object 67 | code under terms of your choice, provided that, if the incorporated 68 | material is not limited to numerical parameters, data structure 69 | layouts and accessors, or small macros, inline functions and templates 70 | (ten or fewer lines in length), you do both of the following: 71 | 72 | a) Give prominent notice with each copy of the object code that the 73 | Library is used in it and that the Library and its use are 74 | covered by this License. 75 | 76 | b) Accompany the object code with a copy of the GNU GPL and this license 77 | document. 78 | 79 | 4. Combined Works. 80 | 81 | You may convey a Combined Work under terms of your choice that, 82 | taken together, effectively do not restrict modification of the 83 | portions of the Library contained in the Combined Work and reverse 84 | engineering for debugging such modifications, if you also do each of 85 | the following: 86 | 87 | a) Give prominent notice with each copy of the Combined Work that 88 | the Library is used in it and that the Library and its use are 89 | covered by this License. 90 | 91 | b) Accompany the Combined Work with a copy of the GNU GPL and this license 92 | document. 93 | 94 | c) For a Combined Work that displays copyright notices during 95 | execution, include the copyright notice for the Library among 96 | these notices, as well as a reference directing the user to the 97 | copies of the GNU GPL and this license document. 98 | 99 | d) Do one of the following: 100 | 101 | 0) Convey the Minimal Corresponding Source under the terms of this 102 | License, and the Corresponding Application Code in a form 103 | suitable for, and under terms that permit, the user to 104 | recombine or relink the Application with a modified version of 105 | the Linked Version to produce a modified Combined Work, in the 106 | manner specified by section 6 of the GNU GPL for conveying 107 | Corresponding Source. 108 | 109 | 1) Use a suitable shared library mechanism for linking with the 110 | Library. A suitable mechanism is one that (a) uses at run time 111 | a copy of the Library already present on the user's computer 112 | system, and (b) will operate properly with a modified version 113 | of the Library that is interface-compatible with the Linked 114 | Version. 115 | 116 | e) Provide Installation Information, but only if you would otherwise 117 | be required to provide such information under section 6 of the 118 | GNU GPL, and only to the extent that such information is 119 | necessary to install and execute a modified version of the 120 | Combined Work produced by recombining or relinking the 121 | Application with a modified version of the Linked Version. (If 122 | you use option 4d0, the Installation Information must accompany 123 | the Minimal Corresponding Source and Corresponding Application 124 | Code. If you use option 4d1, you must provide the Installation 125 | Information in the manner specified by section 6 of the GNU GPL 126 | for conveying Corresponding Source.) 127 | 128 | 5. Combined Libraries. 129 | 130 | You may place library facilities that are a work based on the 131 | Library side by side in a single library together with other library 132 | facilities that are not Applications and are not covered by this 133 | License, and convey such a combined library under terms of your 134 | choice, if you do both of the following: 135 | 136 | a) Accompany the combined library with a copy of the same work based 137 | on the Library, uncombined with any other library facilities, 138 | conveyed under the terms of this License. 139 | 140 | b) Give prominent notice with the combined library that part of it 141 | is a work based on the Library, and explaining where to find the 142 | accompanying uncombined form of the same work. 143 | 144 | 6. Revised Versions of the GNU Lesser General Public License. 145 | 146 | The Free Software Foundation may publish revised and/or new versions 147 | of the GNU Lesser General Public License from time to time. Such new 148 | versions will be similar in spirit to the present version, but may 149 | differ in detail to address new problems or concerns. 150 | 151 | Each version is given a distinguishing version number. If the 152 | Library as you received it specifies that a certain numbered version 153 | of the GNU Lesser General Public License "or any later version" 154 | applies to it, you have the option of following the terms and 155 | conditions either of that published version or of any later version 156 | published by the Free Software Foundation. If the Library as you 157 | received it does not specify a version number of the GNU Lesser 158 | General Public License, you may choose any version of the GNU Lesser 159 | General Public License ever published by the Free Software Foundation. 160 | 161 | If the Library as you received it specifies that a proxy can decide 162 | whether future versions of the GNU Lesser General Public License shall 163 | apply, that proxy's public statement of acceptance of any version is 164 | permanent authorization for you to choose that version for the 165 | Library. 166 | -------------------------------------------------------------------------------- /RCPSpecification.md: -------------------------------------------------------------------------------- 1 | ## RCP Levels: 2 | - __Value__: Number, String, Color, … This is the value without visual representation 3 | - __Widget__ (optional): Button, Slider, … This is the visual representation of a Value. A Widget must be implemented client-side. The protocol defines standard widgets for basic types. Optionally complex types can be added when needed. 4 | - __Layout__ (optional): Placement of widgets on a screen: The Layouting of Widgets defines how widgets are placed on screen by defining standard containers. 5 | - __Style__ (optional): Look (colors, shading, ...) of widgets on a screen: CSS styling of widgets 6 | 7 | The first draft version of RCP only defines 1. (Values) and 2. (Widgets) 8 | 9 | -> Have a look at the [Value Specification](RCPValue.md) 10 | 11 | -> Have a look at the [Widget Specification](RCPWidget.md) 12 | 13 | 14 | ## Endianess 15 | 16 | The format is using big endian 17 | 18 | ## Framing 19 | 20 | Data Framing is not scope of this protocol. 21 | 22 | of interest. use a: 23 | - prefix stream with magic (e.g.: 0x04 0x0F 0x05 0x09) 24 | - SLIP RFC 1055 25 | 26 | ## Types 27 | 28 | - string-tiny: prefixed with size [uint8] followed by [UTF-8 string-data] 29 | - string-short: prefixed with size [uint16] followed by [UTF-8 string-data] 30 | - string: prefixed with size [uint32] followed by [UTF-8 string-data] 31 | - multilanguage: list of: [ISO 639-3](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) language-code (3-bytes in ascii) followed by string-tiny, string-short or string. list is terminated with 0. additional to the ISO 639-3 codes we define a special code for no specific language: "any" 32 | 33 | ## Package 34 | 35 | | Name | ID hex/dec | Value | default value | optional | description | 36 | | --------------|--------------|----------------|-----------------|------------|---------------| 37 | | **command** | - | byte | - | n | command of package | 38 | | timestamp | 0x11(17) | uint64 | 0 | y | optional timestamp | 39 | | data | 0x12(18) | - | - | y | package data. type depends on command | 40 | | **terminator** | 0 | byte | 0 | n | package terminator | 41 | 42 | note: we may want to send id/timestamp before the data, to decide if packet is valid (udp case), prefix the value with data-id. otherwise we need to parse the data before to get id/timestamp 43 | 44 | chaining Parameters: data can contain more than one Parameter. 45 | 46 | ### command table: 47 | 48 | | command | ID | expected data | comment | 49 | |-----------|------|---------------|-----------| 50 | | info | 0x01 | null or Info Data | if no data is sent: it has to be answered with an info command including info data. if data is sent, it must not be answered by an info command. 51 | | initialize | 0x02 | null or ID Data | if no data is sent: request for all parameters. sends update command(s) to client. 52 | | discover | 0x03 | null or ID Data | if no data is sent: request for all parameters. parameters are sent without typdedefinition-options, without value and userdata. discover only discovers on level, no subgroups are discovered. sends update command(s) to client. 53 | | update | 0x04 | Parameter 54 | | remove | 0x05 | ID Data 55 | | updatevalue | 0x06 | specialized smallest update-value format 56 | 57 | - clients usually send: info, discover, initialize, update, updateValue 58 | - server ususally sends: info, add, update, updateValue, remove 59 | 60 | 61 | ## ID Data 62 | 63 | | Name | ID hex/dec | ValueType | default value | optional | description | 64 | | --------------|--------------|----------------|-----------------|------------|---------------| 65 | | **id** | - | int16 | 0 | n | id of parameterGroup or Parameter 66 | 67 | 68 | ## Info Data 69 | 70 | | Name | ID hex/dec | ValueType | default value | optional | description | 71 | | --------------|--------------|----------------|-----------------|------------|---------------| 72 | | **version** | - | tiny-string | "" |n| rcp protocol version 73 | | applicationid | 0x1a (26) | tiny-string | "" |y| Can be used to identify the server/client application 74 | | **terminator** | 0 | 1 byte | 0 | n | terminator 75 | 76 | 77 | ## Parameter: 78 | 79 | | Name | ID hex/dec | ValueType | default value | optional | description | 80 | | --------------|--------------|----------------|-----------------|------------|---------------| 81 | | **id** | - | int16 | - | n | unique identifier (can not be 0. see: parent) 82 | | **typedefinition** | - | TypeDefinition | - | n | typedefinition of value. see: [Value Specification](RCPValue.md) 83 | | value | 0x20 (32) | known from typedefinition | ? | y | value (length is known by type!) 84 | | label | 0x21 (33) | multilanguage string-tiny | "" | y | Human readable identifier 85 | | description | 0x22 (34) | multilanguage string-short | "" | y | can be shown as a tooltip 86 | | tags | 0x23 (35) | string-tiny | "" | y | space separated list of tags 87 | | order | 0x24 (36) | int32 | 0 | y | sorting for parameters. allows for most simple layout: a higher order sorts a parameter after a parameter with a lower order 88 | | parentid | 0x25 (37) | int16 | 0 | y | specifies another parameterGroup as parent. 89 | | widget | 0x26 (38) | widget data | text-input-widget | y | see: [Widget Specification](RCPWidget.md) 90 | | userdata | 0x27 (39) | size-prefixed bytearray | - | y | various user-data. e.g.: metadata, tags, ... 91 | | userid | 0x28 (40) | string-tiny | "" | y | user id 92 | | readonly | 0x29 (41) | byte | false | y | read only 93 | | **terminator** | 0 | 1 byte | 0 | n | terminator 94 | 95 | 96 | ## ParameterGroup: 97 | 98 | A ParameterGroup is a Parameter without value/defaultValue and a fixed TypeDefintion (group). 99 | 100 | A ParameterGroup allows to structure your parameters and can be used to discover parameters on different levels. 101 | 102 | A Parameter can only be child of excactly one group. 103 | 104 | 105 | ## Root Parameter Group 106 | 107 | This parameter group is a virtual Parameter-group which does always exist. 108 | It defines the highes level in the hirarchy tree. 109 | 110 | The id of the root-group is 0. 111 | 112 | No other Parameter is allowed to have this id. 113 | 114 | 115 | ## updateValue 116 | 117 | to optimize the update of the value of a parameter, there is a specialized updateValue command in the form: 118 | 119 | | Name | ID hex/dec | ValueType | default value | optional | description | 120 | | --------------|--------------|----------------|-----------------|------------|---------------| 121 | | **command** | 0x06 | byte | - | n | updateValue command 122 | | **parameter id** | | int16 | 0 | n | parameter id 123 | | **mandatory part of datatype** | | byte | 0 | n | datatype 124 | | **value** | | type of datatype | ? | n | the value 125 | 126 | this reduces the amount of data to be sent for a simple value udpate. 127 | 128 | e.g.: 129 | 130 | updating a int32 with id 0x01 to value 255: 131 | 132 | 0x06 0x01 0x01 0x15 0x00 0x00 0x00 0xFF (8 bytes) 133 | -------------------------------------------------------------------------------- /RCPValue.md: -------------------------------------------------------------------------------- 1 | -> back to [RCP Specification](RCPSpecification.md) 2 |
3 | 4 | ## Typedefinition: 5 | 6 | | Name | ID hex/dec | ValueType | default value | optional | description | 7 | | --------------|--------------|----------------|-----------------|------------|---------------| 8 | | **datatype** | - | byte (see datatype table) | 0x2f | n | type of value 9 | | ... type options... | | |||| 10 | | **terminator** | 0 | byte | 0 | n | terminator 11 |
12 | 13 | ### Datatypes: (1byte) 14 | 15 | | datatype | hex (dec) | length (bytes) | 16 | | -----------|-------------|------------------| 17 | | custom type | 0x01 (1) | defined by typedef | 18 | | boolean | 0x10 (16) | 1 | 19 | | int8 | 0x11 (17) | 1 | 20 | | uint8 | 0x12 (18) | 1 | 21 | | int16 | 0x13 (19) | 2 | 22 | | uint16 | 0x14 (20) | 2 | 23 | | int32 | 0x15 (21) | 4 | 24 | | uint32 | 0x16 (22) | 4 | 25 | | int64 | 0x17 (23) | 8 | 26 | | uint64 | 0x18 (24) | 8 | 27 | | float32 | 0x19 (25) | 4 | 28 | | float64 | 0x1a (26) | 8 | 29 | | Vector2i32 | 0x1b (27) | 2 x 4 | 30 | | Vector2f32 | 0x1c (28) | 2 x 4 | 31 | | Vector3i32 | 0x1d (29) | 3 x 4 | 32 | | Vector3f32 | 0x1e (30) | 3 x 4 | 33 | | Vector4i32 | 0x1f (31) | 4 x 4 | 34 | | Vector4f32 | 0x20 (32) | 4 x 4 | 35 | | String | 0x21 (33) | size prefixed 36 | | RGB | 0x22 (34) | 37 | | RGBA | 0x23 (35) | 38 | | Enum | 0x24 (36) | 39 | | Array | 0x25 (37) | 40 | | List | 0x26 (38) | 41 | | Bang | 0x27 (39) | 0 | 42 | | Group | 0x28 (40) | 0 | 43 | | URI | 0x2a (42) | size prefixed 44 | | IPv4 | 0x2b (43) | 4 45 | | IPv6 | 0x2c (44) | 16 46 | | Range | 0x2d (45) | 47 | | Image | 0x2e (46) | 48 |
49 | 50 | ### Typedefinition Boolean: 51 | 52 | byte value: 53 | - 0 == false 54 | - bigger than 0 == true 55 | 56 | | Name | ID hex/dec | ValueType | default value | optional | description | 57 | | --------------|--------------|----------------|-----------------|------------|---------------| 58 | | default | 0x30 (48) | byte | 0 | y | default value 59 |
60 | 61 | ### Typedefinition Numbers: 62 | 63 | uint8, int8, uint16, int16, ... Vector2f32, Vector2i32, Vector3f32, Vector3i32, ... 64 | see type-table for all number-types. 65 | 66 | | Name | ID hex/dec | ValueType | default value | optional | description | 67 | | --------------|--------------|----------------|-----------------|------------|---------------| 68 | | default | 0x30 (48) | of type | 0 | y | default value 69 | | minimum | 0x31 (49) | of type | minimum of type | y | min value 70 | | maximum | 0x32 (50) | of type | maximum of type | y | max value 71 | | multipleof | 0x33 (51) | of type | 0 | y | multiple of value 72 | | scale | 0x34 (52) | byte | 0 | y | one of these (0x00, 0x01, 0x02) 73 | | unit | 0x35 (53) | string-tiny | "" | y | the unit of value 74 | 75 | #### scale table 76 | 77 | | Name | hex | 78 | |--------|-------| 79 | | Linear | 0x00 | 80 | | Log | 0x01 | 81 | | exp2 | 0x02 | 82 |
83 | 84 | ### Typedefinition Range: 85 | 86 | range for number types: see type-table for all number-types. 87 | 88 | range-data: 89 | 2 consecutive values of type 90 | 91 | | Name | ID hex/dec | ValueType | default value | optional | description | 92 | | --------------|--------------|----------------|-----------------|------------|---------------| 93 | | **elementtype** | - | TypeDefinition | int32 | n | Number TypeDefintion of range element 94 | | default | 0x30 (48) | range-data | element-type-default element-type-default | y | default value 95 |
96 | 97 | ### Typedefinition String: string 98 | 99 | 4-byte size-prefixed UTF-8 string 100 | 101 | | Name | ID hex/dec | ValueType | default value | optional | description | 102 | | --------------|--------------|----------------|-----------------|------------|---------------| 103 | | default | 0x30 (48) | rcp string | 0 - | y | default value 104 | | regular expression | 0x31 (49) | rcp string | "" | y | regular expression to define the form. e.g. limit amount of newlines in text: "\\A(?>[^\r\n]*(?>\r\n?|\n)){0,3}[^\r\n]*\\z" 105 |
106 | 107 | ### Typedefinition Color: RGB, RGBA 108 | 109 | Colors are represented in a 32bit value in byte-order (big-endian) with 8-bits per channel: 110 | 111 | e.g. RGBA: 112 | * Red opaque: 0xFF 0x00 0x00 0xFF 113 | * Red transparent: 0x00 0x00 0x00 0xFF 114 | * Green opaque: 0xFF 0x00 0xFF 0x00 115 | * Blue 50% transparent: 0x80 0xFF 0x00 0x00 116 | 117 | e.g. RGB: 118 | * Red: 0xFF 0x00 0x00 0xFF 119 | * Green: 0xFF 0x00 0xFF 0x00 120 | * Blue: 0xFF 0xFF 0x00 0x00 121 | 122 | 123 | | Name | ID hex/dec | ValueType | default value | optional | description | 124 | | --------------|--------------|----------------|-----------------|------------|---------------| 125 | | default | 0x30 (48) | int32 | 0 | y | default value 126 |
127 | 128 | ### Typedefinition Enum 129 | 130 | | Name | ID hex/dec | ValueType | default value | optional | description | 131 | | --------------|--------------|----------------|-----------------|------------|---------------| 132 | | default | 0x30 (48) | string-tiny | value 0 means: first-element | y | default value 133 | | entries | 0x31 (49) | list of string-tiny, terminated with 0 (0-length string-tiny) | 0 | y | list of enumerations 134 | | multiselect | 0x32 (50) | boolean | false | y | allow multiple selections or not 135 |
136 | 137 | ### Typedefinition Array 138 | 139 | #### rcp-array-structure: 140 | dimension-count followed by elements per dimension 141 | dimension-count: 142 | elements per dimension: dimension-count x 143 | 144 | e.g. 145 | 3-dimensionsal array with 2 times 2 times one elements (int[2][2][1]): 146 | 3 2 2 1 147 | 148 | #### rcp-array-data: 149 | number of bytes defined by the element-type and the structure 150 | 151 | 152 | | Name | ID hex/dec | ValueType | default value | optional | description | 153 | | --------------|--------------|----------------|-----------------|------------|---------------| 154 | | **elementtype** | - | TypeDefinition | - | n | TypeDefintion of array elements (all except array, list) 155 | | **structure** | - | rcp-array-structure | 0 | n | defines the structure of the array: number of dimensions and elements per dimensions 156 | | default | 0x30 (48) | rcp-array-data | - | y | default value 157 |
158 | 159 | ### Typedefinition List 160 | 161 | list-data: 162 | a size-prefixed list of values for each dimension recursively. 163 | 164 | e.g.: 165 | [] –> 0 166 | [0] -> 1 0 167 | [a, b] -> 2 a b 168 | [ [a, b, c], [d, e, f] ] -> 2 3 a b c 3 d e f 169 | [ [a, b, c], [d, e] ] -> 2 3 a b c 2 d e 170 | 171 | 172 | | Name | ID hex/dec | ValueType | default value | optional | description | 173 | | --------------|--------------|----------------|-----------------|------------|---------------| 174 | | **elementtype** | - | TypeDefinition | StringType | n | TypeDefintion of array elements (all except array, list) 175 | | default | 0x30 (48) | list-data | 0 | y | default value 176 | | minimum | 0x32 (50) | one-dimensional list of | 0 | y | minimum length of list per dimension. if minimum length of a dimension is not specified, then the minimum length is 0. 177 | | maximum | 0x33 (51) | one-dimensional list of | 0 | y | maximum length of list per dimension. if maximum length of a dimension is not specified, then the maximum length is max-int. 178 |
179 | 180 | ### URI: 181 | 182 | size-prefixed UTF-8 string forming an URI 183 | 184 | | Name | ID hex/dec | ValueType | default value | optional | description | 185 | | --------------|--------------|----------------|-----------------|------------|---------------| 186 | | default | 0x30 (48) | string | 0 - | y | default value 187 | | filter | 0x31 (49) | string-tiny | - | y | empty (all files), "dir" or a file-filter as defined [here](https://msdn.microsoft.com/en-us/library/system.windows.forms.filedialog.filter(v=vs.110).aspx). 188 | | schema | 0x32 (50) | string-tiny | - | y | space-seperated list with allowed schemas. e.g. "file ftp http https" 189 |
190 | 191 | ### IPv4: 192 | 193 | | Name | ID hex/dec | ValueType | default value | optional | description | 194 | | --------------|--------------|----------------|-----------------|------------|---------------| 195 | | default | 0x30 (48) | 4 bytes | - | y | default value 196 |
197 | 198 | ### IPv6: 199 | 200 | | Name | ID hex/dec | ValueType | default value | optional | description | 201 | | --------------|--------------|----------------|-----------------|------------|---------------| 202 | | default | 0x30 (48) | 16 bytes | - | y | default value 203 |
204 | 205 | ### Image: 206 | 207 | #### rcp-image-data: 208 | size prefix: int32 209 | image-data: bytes of one of the following image-formats: JPEG, PNG, BMP, GIF 210 | 211 | | Name | ID hex/dec | ValueType | default value | optional | description | 212 | | --------------|--------------|----------------|-----------------|------------|---------------| 213 | | default | 0x30 (48) | rcp-image-data | - | y | default image 214 |
215 | 216 | ### Custom Type: 217 | 218 | | Name | ID hex/dec | ValueType | default value | optional | description | 219 | | --------------|--------------|----------------|-----------------|------------|---------------| 220 | | **size** | - | uint32 | - | n | byte-length of type 221 | | default | 0x30 (48) | size-amount of bytes | - | y | default value 222 | | uuid | 0x31 (49) | UUID: 16 bytes | - | y | UUID of custom type. this must be unique to avoid widget-conflicts. !0 223 | | config | 0x32 (50) | 4-byte size-prefixed byte-array | - | y | custom config, can be anything 224 | -------------------------------------------------------------------------------- /RCPWidget.md: -------------------------------------------------------------------------------- 1 | -> back to [RCP Specification](RCPSpecification.md) 2 | 3 | ## Widget (0x24): 4 | 5 | | Name | ID hex/dec | ValueType | default value | optional | description | 6 | | --------------|--------------|----------------|-----------------|------------|---------------| 7 | | **type** | - | uint16 | textbox (0x0011) | n | type of widget. see widget type-table and widget options 8 | | enabled | 0x50 (80) | byte | true | y | if widget allows user input 9 | | label-visible | 0x51 (81) | byte | true | y | if label is visible 10 | | value-visible | 0x52 (82) | byte | true | y | if value is visible 11 | | needs-confirmation | 0x53 (83) | byte | false | y | if input needs to be confirmed 12 | | ... special widget options... | 13 | | **terminator** | 0 | byte | 0 | n | terminator 14 | 15 | 16 | ### Widget type table: 17 | 18 | | typename | hex | description 19 | |------------|-------|--------------| 20 | | Default Widget | 0x0001 | the default widget 21 | | Custom Widget | 0x0002 | a custom widget 22 | | Info | 0x0010 | For discovery: only shows datatype, label. groupParameters are collapsable 23 | | Textbox | 0x0011 | 24 | | Bang | 0x0012 | fires on press 25 | | Press | 0x0013 | onPress sends 1, onRelease sends 0 26 | | Toggle | 0x0014 | Switch: toggles it's state on each press 27 | | Numberbox | 0x0015 | 28 | | Dial | 0x0016 | 29 | | Slider | 0x0017 | 30 | | Slider2d | 0x0018 | 31 | | Range | 0x0019 | 32 | | Dropdown | 0x001a | 33 | | Radiobutton | 0x001b | 34 | | Colorbox | 0x001c | 35 | | Table | 0x001d | 36 | | Filechooser | 0x001e | 37 | | Directorychooser | 0x001f | 38 | | IP | 0x0020 | 39 | | List | 0x8000 | Layouting Widget for Groups 40 | | Listpage | 0x8001 | Layouting Widget for Groups 41 | | Tabs | 0x8002 | Layouting Widget for Groups 42 | 43 | 44 | ### Textbox: 45 | 46 | | Name | ID hex/dec | ValueType | default value | optional | description | 47 | | --------------|--------------|----------------|-----------------|------------|---------------| 48 | | multiline | 0x56 (86) | boolean | false | y | enable/disable multiline textfield 49 | | wordwrap | 0x57 (87) | boolean | false | y | enable/disable word wrap 50 | | password | 0x58 (88) | boolean | false | y | enable/disable if testbox is a password input 51 | 52 | 53 | ### Numberbox: 54 | 55 | | Name | ID hex/dec | ValueType | default value | optional | description | 56 | | --------------|--------------|----------------|-----------------|------------|---------------| 57 | | precision | 0x56 (86) | uint8 | 2 | y | set precision for numberbox 58 | | format | 0x57 (87) | uint8 | 0x01 | y | set format of numberbox: dec/hex/bin 59 | | stepsize | 0x58 (88) | T of value | if Value.multipleof > 0, then value.multipleof. Else dependent on value.subtype: If real: 0.01. If int: 1 | y | a value always must be within it’s definition. Therefore If stepsize collides with value.multipleof, then value.multipleof is used: to keep value within it’s defintion. 60 | | cyclic | 0x59 (89) | boolean | false | y | inspector should wrap around value 61 | 62 | ## format table: 63 | 64 | | typename | hex | 65 | |------------|-------| 66 | | dec | 0x01 | 67 | | hex | 0x02 | 68 | | bin | 0x03 | 69 | 70 | 71 | ### Dial: 72 | 73 | | Name | ID hex/dec | ValueType | default value | optional | description | 74 | | --------------|--------------|----------------|-----------------|------------|---------------| 75 | | cyclic | 0x56 (86) | boolean | false | y | if dial is cyclic 76 | 77 | 78 | ### Slider: 79 | 80 | | Name | ID hex/dec | ValueType | default value | optional | description | 81 | | --------------|--------------|----------------|-----------------|------------|---------------| 82 | | horizontal | 0x56 (86) | boolean | true | y | if slider is horizontal 83 | 84 | 85 | ### Table: 86 | work-in-progress: 87 | option: labels for dimensions: array of labels 88 | 89 | 90 | ### Range: 91 | ``` 92 | min max 93 | |----------------------------| 94 | |------| 95 | v1 v2 96 | ``` 97 | 98 | ### Custom Widget: 99 | 100 | | Name | ID hex/dec | ValueType | default value | optional | description | 101 | | --------------|--------------|----------------|-----------------|------------|---------------| 102 | | uuid | 0x56 (86) | UUID: 16-byte | 0 | y | UUID of custom widget. this must be unique to avoid widget-conflicts. !0 103 | | config | 0x57 (87) | 4-byte size-prefixed byte-array | - | y | custom config, can be anything 104 | -------------------------------------------------------------------------------- /RCP_diagram.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | e.g.: RCP Client on Mobile 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | e.g.: RCP Client on Laptop 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | Host Application 45 | C++, C#, Java, vvvv, openFrameworks, ... 46 | 47 | (uses RCP Library to expose Parameter) 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | Checkbox 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | button 1 74 | 75 | 76 | 77 | 78 | 79 | 80 | button 2 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | Checkbox 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | button 1 107 | 108 | 109 | 110 | 111 | 112 | 113 | button 2 114 | 115 | 116 | 117 | 118 | 119 | 120 | RCP Client shows GUI 121 | to control Parameters 122 | on Host Application via RCP 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | RCP via Websocket 132 | 133 | 134 | 135 | RCP via TCP 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ![Alt RCP diagram](./RCP_diagram.svg) 2 | (RCP example to control a host application from other devices) 3 | 4 | [rabbitcontrol.cc](http://rabbitcontrol.cc) 5 | 6 | # RCP 7 | Remote Control Protocol 8 | 9 | A binary data-format definition to describe data values and user interface elements. 10 | It is intended to expose parameters (values) from a host application to a client in a defined way. It was created with UI clients in mind which update values at the host application. It can also be used in a non-UI case. 11 | 12 | For details see [Specification](RCPSpecification.md) 13 | 14 | [F.A.Q.](https://github.com/rabbitControl/RCP/wiki/F.A.Q.) 15 | 16 | ## Status 17 | 18 | Work in progress 19 | Request for Comments (RFC) 20 | 21 | Join us in the chat on matrix: 22 | https://matrix.to/#/#rcp:matrix.org 23 | 24 | Follow us on mastodon: 25 | https://vis.social/@rabbitcontrol 26 | -------------------------------------------------------------------------------- /example_data/multi_packet_s8-broken2.rcp: -------------------------------------------------------------------------------- 1 |  !anylabel"any a description !anylabe2"any a description !anylabe2"any a description -------------------------------------------------------------------------------- /example_data/multi_packet_s8.rcp: -------------------------------------------------------------------------------- 1 |  !anylabel"any a description !anylabe2"any a description -------------------------------------------------------------------------------- /example_data/packet_bool_no_user.rcp: -------------------------------------------------------------------------------- 1 |  !any the boolean"any a description$ -------------------------------------------------------------------------------- /example_data/packet_bool_userdata.rcp: -------------------------------------------------------------------------------- 1 | '" -------------------------------------------------------------------------------- /example_data/packet_enum.rcp: -------------------------------------------------------------------------------- 1 | $1option 1option 2option 3 option 1!anyoptions"anyenum with three options# cool options -------------------------------------------------------------------------------- /example_data/packet_info.rcp: -------------------------------------------------------------------------------- 1 | 0.0.0test -------------------------------------------------------------------------------- /example_data/packet_info_nodata.rcp: -------------------------------------------------------------------------------- 1 |  -------------------------------------------------------------------------------- /example_data/packet_initialize.rcp: -------------------------------------------------------------------------------- 1 |  -------------------------------------------------------------------------------- /example_data/packet_initialize_id_data.rcp: -------------------------------------------------------------------------------- 1 |  -------------------------------------------------------------------------------- /example_data/packet_lstr_no_user.rcp: -------------------------------------------------------------------------------- 1 | ! unit description!anythe label of the value"any a description$ -------------------------------------------------------------------------------- /example_data/packet_range.rcp: -------------------------------------------------------------------------------- 1 | -0120  -------------------------------------------------------------------------------- /example_data/packet_remove.rcp: -------------------------------------------------------------------------------- 1 |  -------------------------------------------------------------------------------- /example_data/packet_s16_no_user.rcp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rabbitControl/RCP/651cccf8f34d7cb9768cc183086ba33659d64e42/example_data/packet_s16_no_user.rcp -------------------------------------------------------------------------------- /example_data/packet_s32_no_user.rcp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rabbitControl/RCP/651cccf8f34d7cb9768cc183086ba33659d64e42/example_data/packet_s32_no_user.rcp -------------------------------------------------------------------------------- /example_data/packet_s8_no_user.rcp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rabbitControl/RCP/651cccf8f34d7cb9768cc183086ba33659d64e42/example_data/packet_s8_no_user.rcp -------------------------------------------------------------------------------- /example_data/packet_string_default.rcp: -------------------------------------------------------------------------------- 1 | !0default-string this is a string-value!any filelabel"anyfile description# tag1 tag2 -------------------------------------------------------------------------------- /example_data/packet_u16_no_user.rcp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rabbitControl/RCP/651cccf8f34d7cb9768cc183086ba33659d64e42/example_data/packet_u16_no_user.rcp -------------------------------------------------------------------------------- /example_data/packet_u32_no_user.rcp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rabbitControl/RCP/651cccf8f34d7cb9768cc183086ba33659d64e42/example_data/packet_u32_no_user.rcp -------------------------------------------------------------------------------- /example_data/packet_u8_no_user.rcp: -------------------------------------------------------------------------------- 1 | 012345unit description !anythe label of the value"any a description$ -------------------------------------------------------------------------------- /example_data/packet_update_array_int8.rcp: -------------------------------------------------------------------------------- 1 | %0 %0  -------------------------------------------------------------------------------- /example_data/packet_update_bool.rcp: -------------------------------------------------------------------------------- 1 |   -------------------------------------------------------------------------------- /example_data/packet_update_boolarray_no_user.rcp: -------------------------------------------------------------------------------- 1 | %10 !any the boolean"any a description$ -------------------------------------------------------------------------------- /example_data/packet_update_i16.rcp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rabbitControl/RCP/651cccf8f34d7cb9768cc183086ba33659d64e42/example_data/packet_update_i16.rcp -------------------------------------------------------------------------------- /example_data/packet_update_i32.rcp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rabbitControl/RCP/651cccf8f34d7cb9768cc183086ba33659d64e42/example_data/packet_update_i32.rcp -------------------------------------------------------------------------------- /example_data/packet_update_i8.rcp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rabbitControl/RCP/651cccf8f34d7cb9768cc183086ba33659d64e42/example_data/packet_update_i8.rcp -------------------------------------------------------------------------------- /example_data/packet_update_u16.rcp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rabbitControl/RCP/651cccf8f34d7cb9768cc183086ba33659d64e42/example_data/packet_update_u16.rcp -------------------------------------------------------------------------------- /example_data/packet_update_u32.rcp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rabbitControl/RCP/651cccf8f34d7cb9768cc183086ba33659d64e42/example_data/packet_update_u32.rcp -------------------------------------------------------------------------------- /example_data/packet_update_u8.rcp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rabbitControl/RCP/651cccf8f34d7cb9768cc183086ba33659d64e42/example_data/packet_update_u8.rcp -------------------------------------------------------------------------------- /example_data/packet_updatevalue_s16.rcp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rabbitControl/RCP/651cccf8f34d7cb9768cc183086ba33659d64e42/example_data/packet_updatevalue_s16.rcp -------------------------------------------------------------------------------- /example_data/packet_updatevalue_s32.rcp: -------------------------------------------------------------------------------- 1 | 0 -------------------------------------------------------------------------------- /example_data/packet_updatevalue_s8.rcp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rabbitControl/RCP/651cccf8f34d7cb9768cc183086ba33659d64e42/example_data/packet_updatevalue_s8.rcp -------------------------------------------------------------------------------- /example_data/packet_updatevalue_string.rcp: -------------------------------------------------------------------------------- 1 | ! new_value -------------------------------------------------------------------------------- /example_data/packet_updatevalue_u16.rcp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rabbitControl/RCP/651cccf8f34d7cb9768cc183086ba33659d64e42/example_data/packet_updatevalue_u16.rcp -------------------------------------------------------------------------------- /example_data/packet_updatevalue_u32.rcp: -------------------------------------------------------------------------------- 1 | 0 -------------------------------------------------------------------------------- /example_data/packet_updatevalue_u8.rcp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/rabbitControl/RCP/651cccf8f34d7cb9768cc183086ba33659d64e42/example_data/packet_updatevalue_u8.rcp -------------------------------------------------------------------------------- /example_data/packet_uri.rcp: -------------------------------------------------------------------------------- 1 | *0default-string1,Text files (*.txt)|*.txt|All files (*.*)|*.*2 file http ftp file:///Users/inx!any uri label"anyuri description# tag1 tag2 -------------------------------------------------------------------------------- /example_data/parameter_s8_no_user.rcp: -------------------------------------------------------------------------------- 1 | 012345unit description !anythe label of the value"any a description$ -------------------------------------------------------------------------------- /kaitai/RCPTypes.ksy: -------------------------------------------------------------------------------- 1 | meta: 2 | id: rcp_types 3 | file-extension: rcp 4 | endian: be 5 | 6 | enums: 7 | packet_options: 8 | 0x11: timestamp 9 | 0x12: data 10 | 11 | command: 12 | 0x00: invalid 13 | 0x01: info 14 | 0x02: initialize 15 | 0x03: discover 16 | 0x04: update 17 | 0x05: remove 18 | 0x06: updatevalue 19 | 20 | infodata_options: 21 | 0x1a: applicationid 22 | 23 | parameter_options: 24 | 0x20: value 25 | 0x21: label 26 | 0x22: description 27 | 0x23: tags 28 | 0x24: order 29 | 0x25: parentid 30 | 0x26: widget 31 | 0x27: userdata 32 | 0x28: userid 33 | 0x29: readonly 34 | 35 | boolean_options: 36 | 0x30: default 37 | 38 | number_options: 39 | 0x30: default 40 | 0x31: minimum 41 | 0x32: maximum 42 | 0x33: multipleof 43 | 0x34: scale 44 | 0x35: unit 45 | 46 | vector_options: 47 | 0x30: default 48 | 0x31: minimum 49 | 0x32: maximum 50 | 0x33: multipleof 51 | 0x34: scale 52 | 0x35: unit 53 | 54 | string_options: 55 | 0x30: default 56 | 0x31: regular_expression 57 | 58 | color_options: 59 | 0x30: default 60 | 61 | enum_options: 62 | 0x30: default 63 | 0x31: entries 64 | 0x32: multiselect 65 | 66 | array_options: 67 | 0x30: default 68 | 69 | list_options: 70 | 0x30: default 71 | 0x31: minimum 72 | 0x32: maximum 73 | 74 | uri_options: 75 | 0x30: default 76 | 0x31: filter 77 | 0x32: schema 78 | 79 | ipv4_options: 80 | 0x30: default 81 | 82 | ipv6_options: 83 | 0x30: default 84 | 85 | customtype_options: 86 | 0x30: default 87 | 0x31: uuid 88 | 0x32: config 89 | 90 | range_options: 91 | 0x30: default 92 | 93 | datatype: 94 | 0x01: customtype 95 | 0x10: boolean 96 | 0x11: int8 97 | 0x12: uint8 98 | 0x13: int16 99 | 0x14: uint16 100 | 0x15: int32 101 | 0x16: uint32 102 | 0x17: int64 103 | 0x18: uint64 104 | 0x19: float32 105 | 0x1a: float64 106 | 0x1b: vector2i32 107 | 0x1c: vector2f32 108 | 0x1d: vector3i32 109 | 0x1e: vector3f32 110 | 0x1f: vector4i32 111 | 0x20: vector4f32 112 | 0x21: string 113 | 0x22: rgb 114 | 0x23: rgba 115 | 0x24: enum 116 | 0x25: array 117 | 0x26: list 118 | 0x27: bang 119 | 0x28: group # parameter group 120 | 0x2a: uri 121 | 0x2b: ipv4 122 | 0x2c: ipv6 123 | 0x2d: range 124 | 0x2e: image 125 | 126 | number_scale: 127 | 0x00: linear 128 | 0x01: logarithmic 129 | 0x02: exp2 130 | 131 | widget_options: 132 | 0x50: enabled 133 | 0x51: label_visible 134 | 0x52: value_visible 135 | 0x53: needs_confirmation 136 | 137 | label_position: 138 | 0x01: left 139 | 0x02: right 140 | 0x03: top 141 | 0x04: bottom 142 | 0x05: center 143 | 144 | widgettype: 145 | 0x0001: default 146 | 0x0002: custom 147 | 0x0010: info 148 | 0x0011: textbox 149 | 0x0012: bang 150 | 0x0013: press 151 | 0x0014: toggle 152 | 0x0015: numberbox 153 | 0x0016: dial 154 | 0x0017: slider 155 | 0x0018: slider2d 156 | 0x0019: range 157 | 0x001a: dropdown 158 | 0x001b: radiobutton 159 | 0x001c: colorbox 160 | 0x001d: table 161 | 0x001e: filechooser 162 | 0x001f: directorychooser 163 | 0x0020: ip 164 | 0x8000: list 165 | 0x8001: listpage 166 | 0x8002: tabs 167 | 168 | 169 | textbox_options: 170 | 0x56: multiline 171 | 0x57: wordwrap 172 | 0x58: password 173 | 174 | numberbox_options: 175 | 0x56: precision 176 | 0x57: format 177 | 0x58: stepsize 178 | 0x59: cyclic 179 | 180 | numberbox_format: 181 | 0x01: dec 182 | 0x02: hex 183 | 0x03: bin 184 | 185 | slider_options: 186 | 0x56: horizontal 187 | 188 | dial_options: 189 | 0x56: cyclic 190 | 191 | customwidget_options: 192 | 0x56: uuid 193 | 0x57: config 194 | 195 | client_status: 196 | 0x00: disconnected 197 | 0x01: connected 198 | 0x02: version_missmatch 199 | 0x03: ok 200 | 201 | types: 202 | tiny_string: 203 | seq: 204 | - id: my_len 205 | type: u1 206 | - id: data 207 | type: str 208 | size: my_len 209 | encoding: UTF-8 210 | short_string: 211 | seq: 212 | - id: my_len 213 | type: u2 214 | - id: data 215 | type: str 216 | size: my_len 217 | encoding: UTF-8 218 | long_string: 219 | seq: 220 | - id: my_len 221 | type: u4 222 | - id: data 223 | type: str 224 | size: my_len 225 | encoding: UTF-8 226 | userdata: 227 | seq: 228 | - id: my_len 229 | type: u4 230 | - id: data 231 | size: my_len 232 | --------------------------------------------------------------------------------