1 (edited by Guillaume 2017-03-02 01:22:08)

Topic: Manual modification of the array

  • This information is for RemoteXY library version 2.2.5, it may not work in future versions.

  • Please read 2 or 3 times before asking questions.



Full description of the array:

The array is made of an header, followed by Elements, sorted by category :

CONF =
{
  HEADER,
  INPUTS,
  OUTPUTS,
  DECORATIONS
}

Legend:

HF : Header Flags
SO : Screen Orientation
PE : Pages Enabled

 
Header:

The array starts with 7 bytes that forms the header:

Header bytes :  A  B  C  D  E  F  G
Default value : 0, 0, 3, 0, 6, 5, 0

A   : Total bytes used by inputs in the struct, see an input's decription below for details
B   : Total bytes used by outputs in the struct, see an output's decription below for details
C-D : 16 bits number (C is the low byte, D is the high byte).
      This number is the size of the array minus 4 (number of bytes after D until the end of the array).
      In a new empty project, there is only the header in the array, so there are 3 bytes after D, so C-D = 3
E   : ? Array version ? Doesn't seem to change.
F   : Background Color2
G   : HF Bits
        0-1 : SO ( 0b00 = landscape, 0b01 = portrait, 0b10 = both )
        2   : PE ( 0 = no, 1 = yes ). Set this bit to 1 if you use one or more Page elements.
      Example : 0b00000101 (5) : pages enabled = yes, screen orientation = portrait

A, B and C-D must be increased according to each Element you add in the array. See below each Element's description for details.



Elements:

The value of HF defines how much bytes an Element will add in the array:

  • If SO = 0b10 (both), then 4 additional bytes, X2, Y2, W2 and H2, are required by an Element, after the H1 byte, to set the position and size for the Portrait orientation.

  • If PE = 1, then 1 additional byte, P, is required by an Element, after the Color byte, to set the page ID this Element must be attached to. Setting this byte to 0 will show the Element on all Pages.


The code boxes below describes each byte of each Element. The values shown are the default values when adding the Element in the top left corner.


General information and legend:

  • T : Type of the Element (Button = 1, LED = 65, Panel = 130, etc)

  • F : Flags

  • If SO = Landscape OR Portrait :
      X1, Y1, W1, H1 are values for the choosen orientation (obviously)
      X2, Y2, W2, H2 must not exist!
    else if SO = Both :
      X1, Y1, W1, H1 are values for the landscape orientation
      X2, Y2, W2, H2 are values for the portrait orientation

  • X1,X2 : position of the left edge of the Element :
    Landscape: 0 (left) to 100 (right), can be set to < 0 or > 100 for moving outside of editor's screen.
    Portrait:  0 (left) to 63  (right), can be set to < 0 or >  63 for moving outside of editor's screen.

  • Y1,Y2 : position of the top edge of the Element :
    Landscape : 0  (top) to  63 (bottom), can be set to < 0 or >  63 for moving outside of editor's screen.
    Portrait: 0  (top) to 100 (bottom), can be set to < 0 or > 100 for moving outside of editor's screen.

  • W1,W2 : width of the Element

  • H1,H2 : height of the Element

  • C : Color1:https://i.solidfiles.com/62MLQYA5qpk6Z.png Color2:https://i.solidfiles.com/Wwj5YM63qkgeq.png

  • P : PageID of the corresponding Page Element, or set to 0 to show on all Pages.
    This byte must not exist if PE = 0.




Inputs

BUTTON

HF VALUE            ELEMENT BYTES                                LENGTH
                    T  F X1 Y1 W1 H1 X2 Y2 W2 H2  C  P  x...  
0b000 or 0b001      1, 0, 0, 0,12,12,             2,   88, 0     7 + n
0b100 or 0b101      1, 0, 0, 0,12,12,             2, 0,88, 0     8 + n
0b010               1, 0, 0, 0,12,12, 0, 0,12,12, 2,   88, 0     11 + n
0b110               1, 0, 0, 0,12,12, 0, 0,12,12, 2, 0,88, 0     12 + n

n : Length of the caption string, including null character.
F : Bits
      0 : shape ( 0 = round, 1 = rectangular )
    Example : 0b00000001 (1) : shape = rectangular
C : Color1
x : Caption (null-terminated ASCII string)

Header bytes :                 A  B  C  D  E  F  G
Default value :                0, 0, 3, 0, 6, 5, 0
After adding default Button:   1, 0,12, 0, 6, 5, 0
A += 1 : requires one input variable
C += 9 : HF = 0b000, so Length = 7 + 2 characters ("X\0")

SWITCH

HF VALUE            ELEMENT BYTES                                               LENGTH
                    T  F X1 Y1 W1 H1 X2 Y2 W2 H2  C  P  x..................
0b000 or 0b001      2, 0, 0, 0,22,11,             2,   79,78, 0,79,70,70, 0     7 + n
0b100 or 0b101      2, 0, 0, 0,22,11,             2, 0,79,78, 0,79,70,70, 0     8 + n
0b010               2, 0, 0, 0,22,11, 0, 0,22,11, 2,   79,78, 0,79,70,70, 0     11 + n
0b110               2, 0, 0, 0,22,11, 0, 0,22,11, 2, 0,79,78, 0,79,70,70, 0     12 + n

n : Length of both captions strings including both null characters.
F : Unused, always = 0
C : Color1
x : Caption ON and Caption OFF (null-terminated ASCII strings)

Header bytes :                 A  B  C  D  E  F  G
Default value :                0, 0, 3, 0, 6, 5, 0
After adding default Switch:   1, 0,17, 0, 6, 5, 0
A += 1  : requires one input variable
C += 14 : HF = 0b000, so Length = 7 + 7 characters ("ON\0OFF\0")

SELECT

HF VALUE            ELEMENT BYTES                          LENGTH
                    T  F X1 Y1 W1 H1 X2 Y2 W2 H2  C  P
0b000 or 0b001      3, 3, 0, 0, 8,22,             2        7
0b100 or 0b101      3, 3, 0, 0, 8,22,             2, 0     8
0b010               3, 3, 0, 0, 8,22, 0, 0, 8,22, 2        11
0b110               3, 3, 0, 0, 8,22, 0, 0, 8,22, 2, 0     12

F : Bit
      0-3 : count of positions (ex: 0b0101 = 5)
      7   : orientation ( 0 = vertical, 1 = horizontal )
    Example: 0b10000101 (133) : orientation = horizontal, positions = 5
C : Color1

Header bytes :                 A  B  C  D  E  F  G
Default value :                0, 0, 3, 0, 6, 5, 0
After adding default Select:   1, 0,10, 0, 6, 5, 0
A += 1 : requires one input variable
C += 7 : HF = 0b000, so Length = 7

SLIDER

HF VALUE             ELEMENT BYTES                          LENGTH
                     T  F X1 Y1 W1 H1 X2 Y2 W2 H2  C  P
0b000 or 0b001       4, 0, 0, 0, 7,18,             2        7
0b100 or 0b101       4, 0, 0, 0, 7,18,             2, 0     8
0b010                4, 0, 0, 0, 7,18, 0, 0, 7,18, 2        11
0b110                4, 0, 0, 0, 7,18, 0, 0, 7,18, 2, 0     12

F : Bit
      4   : automatically center ( 0 = disabled, 1 = enabled )
      5-6 : slider center pos 00 = bottom, 01 = middle, 10 = top
      7   : orientation ( 0 = vertical, 1 = horizontal )
    Example: 0b11010000 (208) : orientation = horizontal, center pos = top, auto center = enabled
C : Color1

Header bytes :                 A  B  C  D  E  F  G
Default value :                0, 0, 3, 0, 6, 5, 0
After adding default Slider:   1, 0,10, 0, 6, 5, 0
A += 1 : requires one input variable
C += 7 : HF = 0b000, so Length = 7

JOYSTICK

HF VALUE            ELEMENT BYTES                            LENGTH
                    T  F X1 Y1 W1 H1 X2 Y2 W2 H2  C  P
0b000 or 0b001      5, 0, 0, 0,30,30,             2          7
0b100 or 0b101      5, 0, 0, 0,30,30,             2, 0       8
0b010               5, 0, 0, 0,30,30, 0, 0,30,30, 2          11
0b110               5, 0, 0, 0,30,30, 0, 0,30,30, 2, 0       12

F : Bit
      0-4 : center button and g-sensor button's positions:
              center   : hide = 0, TR = 1, BR =  2, BL =  3, TL =  4
              g-sensor : hide = 0, TR = 5, BR = 10, BL = 15, TL = 20
              value = CB + GSB, example : (CB = BR = 2) + (GSB = TL = 20) = 22
      5   : automatically center ( 0 = disabled, 1 = enabled )
    Example : 0b00101011 (43) : auto center = enabled, center button pos = TR, g-sensor button pos = BR
C : Color1

Header bytes :                 A  B  C  D  E  F  G
Default value :                0, 0, 3, 0, 6, 5, 0
After adding default Joystick: 2, 0,10, 0, 6, 5, 0
A += 2 : requires 2 inputs variables (X and Y)
C += 7 : HF = 0b000, so Length = 7

COLOR PICKER

HF VALUE            ELEMENT BYTES                            LENGTH
                    T  F X1 Y1 W1 H1 X2 Y2 W2 H2  C  P
0b000 or 0b001      6, 0, 0, 0,20,20,             2          7
0b100 or 0b101      6, 0, 0, 0,20,20,             2, 0       8
0b010               6, 0, 0, 0,20,20, 0, 0,20,20, 2          11
0b110               6, 0, 0, 0,20,20, 0, 0,20,20, 2, 0       12

F : Unused, always = 0
C : Color1

Header bytes :                      A  B  C  D  E  F  G
Default value :                     0, 0, 3, 0, 6, 5, 0
After adding default Color Picker : 3, 0,10, 0, 6, 5, 0
A += 3 : requires 3 inputs variables (R, G, B)
C += 7 : HF = 0b000, so Length = 7

EDIT FIELD

HF VALUE            ELEMENT BYTES                             LENGTH
                    T  F X1 Y1 W1 H1 X2 Y2 W2 H2  C  P  x
0b000 or 0b001      7,36, 0, 0,20, 5,             2,   11     7 or 8*
0b100 or 0b101      7,36, 0, 0,20, 5,             2, 0,11     8 or 9*
0b010               7,36, 0, 0,20, 5, 0, 0,20, 5, 2,   11     11 or 12*
0b110               7,36, 0, 0,20, 5, 0, 0,20, 5, 2, 0,11     12 or 13*
   
* Depending on Input type (see F and x below)

F : Bit
      0-1 : Align ( 0b00 = left, 0b01 = center, 0b10 = right )
      2   : Background ( 0 = hide, 1 = show )
      3-4 : Input type ( 0b00 = string, 0b01 = float, 0b10 = integer )
      5   : Clear button ( 0 = hide, 1 = show )
    Example : 0b00001101 (13) : clear button = hide, type = float, background = show, align = center
C : Color1
x : Only required if Input type is String or Float. If type is Integer, do not put this byte in the array.
      If type is String, this byte is the max text length.
      If type is Float, it's the amount of decimals :
        0 = not limited
        1..7 = n-1 decimals, example : 3 = 2 decimals
        
Header bytes :                    A  B  C  D  E  F  G
Default value :                   0, 0, 3, 0, 6, 5, 0
After adding default Edit Field: 11, 0,11, 0, 6, 5, 0
A += 11 : requires 11 characters
C +=  8 : HF = 0b000, Input Type = String, so Length = 8



Outputs:

LED

HF VALUE            ELEMENT BYTES                            LENGTH
                    T  F X1 Y1 W1 H1 X2 Y2 W2 H2  C  P
0b000 or 0b001     65, 4, 0, 0, 9, 9,             2          7
0b100 or 0b101     65, 4, 0, 0, 9, 9,             2, 0       8
0b010              65, 4, 0, 0, 9, 9, 0, 0, 9, 9, 2          11
0b110              65, 4, 0, 0, 9, 9, 0, 0, 9, 9, 2, 0       12

F : Bit
      0-2 : BGR color channels ( 0 = channel disabled, 1 = channel enabled )
      3   : Shape ( 0 = round, 1 = rectangular )
    Example : 0b00001100 (12) : shape = rectangular, color = red
H1 : if shape = round, this byte should have the same value than W1 )
H2 : if shape = round, this byte should have the same value than W2 )
C : Unused, always = 2

Header bytes :            A  B  C  D  E  F  G
Default value :           0, 0, 3, 0, 6, 5, 0
After adding default LED: 0, 1,10, 0, 6, 5, 0
B += 1 : requires one output per R,G,B channel: default LED is red only, so one output is required.
C += 7 : HF = 0b000, so Length = 7

LEVELS

HF VALUE            ELEMENT BYTES                            LENGTH
                    T  F X1 Y1 W1 H1 X2 Y2 W2 H2  C  P
0b000 or 0b001     66, 1, 0, 0, 7,16,             2          7
0b100 or 0b101     66, 1, 0, 0, 7,16,             2, 0       8
0b010              66, 1, 0, 0, 7,16, 0, 0, 7,16, 2          11
0b110              66, 1, 0, 0, 7,16, 0, 0, 7,16, 2, 0       12

F : Bit
      0-2 : Type ( 0b001 = linear, 0b010 = arc, 0b011 = linear division, 0b100 = arc division )
      5-6 : Center pos ( 0b00 = left/bottom, 0b01 = middle, 0b10 = right/top )
      7   : Orientation ( 0 = vertical, 1 = horizontal )
    Example : 0b00100010 (34) : type = arc level, orientation = vertical, center pos = middle
C : Color1

Header bytes :                      A  B  C  D  E  F  G
Default value :                     0, 0, 3, 0, 6, 5, 0
After adding default Linear Level : 0, 1,10, 0, 6, 5, 0
B += 1 : requires one output.
C += 7 : HF = 0b000, so Length = 7

TEXT STRING

HF VALUE            ELEMENT BYTES                              LENGTH
                    T  F X1 Y1 W1 H1 X2 Y2 W2 H2  C  P  L
0b000 or 0b001     67, 4, 0, 0,20, 5,             2,   11      8
0b100 or 0b101     67, 4, 0, 0,20, 5,             2, 0,11      9
0b010              67, 4, 0, 0,20, 5, 0, 0,20, 5, 2,   11      12
0b110              67, 4, 0, 0,20, 5, 0, 0,20, 5, 2, 0,11      13

F : Bit
      0-1 : Align ( 0b00 = left, 0b01 = center, 0b10 = right )
      2   : Background ( 0 = hide, 1 = show )
    Example : 0b00000110 (34) : background = show, align = right
C : Color1
L : Max string length

Header bytes :                     A  B  C  D  E  F  G
Default value :                    0, 0, 3, 0, 6, 5, 0
After adding default Text String : 0,11,11, 0, 6, 5, 0
B += 11 : the max text lenght is 10, so 11 for null at the end of string.
C += 8  : HF = 0b000, so Length = 8



Decoration:

LABEL

HF VALUE            ELEMENT BYTES                                              LENGTH
                    T  F X1 Y1 W1 H1 X2 Y2 W2 H2  C  P  x.................
0b000 or 0b001    129, 0, 0, 0,18, 6,             9,   76,97,98,101,108, 0     7 + n
0b100 or 0b101    129, 0, 0, 0,18, 6,             9, 0,76,97,98,101,108, 0     8 + n
0b010             129, 0, 0, 0,18, 6, 0, 0,18, 6, 9,   76,97,98,101,108, 0     11 + n
0b110             129, 0, 0, 0,18, 6, 0, 0,18, 6, 9, 0,76,97,98,101,108, 0     12 + n

n : Length of the label string, including null character.
F : Unused, always = 0
C : Color2
x : Text (null-terminated ASCII strings)

Header bytes :               A  B  C  D  E  F  G
Default value :              0, 0, 3, 0, 6, 5, 0
After adding default Label : 0, 0,16, 0, 6, 5, 0
C += 13 : HF = 0b000, so Length = 7 + 6 characters ("Label\0")

PANEL

HF VALUE            ELEMENT BYTES                           LENGTH
                    T  F X1 Y1 W1 H1 X2 Y2 W2 H2  C  P
0b000 or 0b001    130, 1, 0, 0,20,20,             9         7
0b100 or 0b101    130, 1, 0, 0,20,20,             9, 0      8
0b010             130, 1, 0, 0,20,20, 0, 0,20,20, 9         11
0b110             130, 1, 0, 0,20,20, 0, 0,20,20, 9, 0      12

F : Bit
      0-2 : bevel cut( 0b00 = linear, 0b01 = raised, 0b10 = lowered )
    Example 0b00000010 (2) : bevel cut = lowered
C : Color2

Header bytes :               A  B  C  D  E  F  G
Default value :              0, 0, 3, 0, 6, 5, 0
After adding default Panel : 0, 0,10, 0, 6, 5, 0
C += 7 : HF = 0b000, so Length = 7

PAGE

HF VALUE            ELEMENT BYTES                                          LENGTH
                    T  F X1 Y1 W1 H1 X2 Y2 W2 H2  C  P  x.............
0b100 or 0b101    131, 1, 0, 0,20, 7,             2, 1,80,97,103,101,0     8 + n
0b110             131, 1, 0, 0,20, 7, 0, 0,20, 7, 2, 1,80,97,103,101,0     12 + n

n : Length of the Page name string, including null character.
F : Bit
      0 : main page ( 0 = no, 1 = yes ) (only one page can be the main page!)
    Example : 0b00000001 (1) : main page = yes
C : Color1
P : Page ID, starts at 1, must be increased for each page
x : Page name (null-terminated ASCII strings)

Header bytes :              A  B  C  D  E  F  G
Default value :             0, 0, 3, 0, 6, 5, 0
After adding default Page : 0, 0,16, 0, 6, 5, 4
C += 13 : After adding the Page Element, HF = 0b100, so Length = 8 + 5 characters ("Page\0")
G = HF = 0b100 = 4




How to manually modify or create the array?

Editing the array and struct in the code can be much faster than building with the editor! So how do we do that?


First, let's take a look at an example project. With the Editor, I added a few Elements randomly to an empty new project, in this order:

  • Button

  • Switch

  • LED

  • Linear Level

  • Another Button

  • Another Switch


This is the generated code

uint8_t RemoteXY_CONF[] =
  { 4,2,63,0,6,5,0,1,0,4
  ,4,12,12,2,88,0,2,0,21,4
  ,22,11,2,79,78,0,79,70,70,0
  ,1,0,79,3,12,12,2,88,0,2
  ,0,4,23,22,11,2,79,78,0,79
  ,70,70,0,65,4,50,5,9,9,2
  ,66,1,65,3,7,16,2 };
  
// this structure defines all the variables of your control interface 
struct {

    // input variable
  uint8_t button_1; // =1 if button pressed, else =0 
  uint8_t switch_1; // =1 if switch ON and =0 if OFF 
  uint8_t button_2; // =1 if button pressed, else =0 
  uint8_t switch_2; // =1 if switch ON and =0 if OFF 

    // output variable
  uint8_t led_1_r; // =0..255 LED Red brightness 
  int8_t level_1; // =0..100 level position 

    // other variable
  uint8_t connect_flag;  // =1 if wire connected, else =0 

} RemoteXY;

Now let's split the array according to what we have learned previously wink

uint8_t RemoteXY_CONF[] =
{
    // header is 7 bytes
    // byte G (last byte) = 0, so HF = 0b000 
    4,2,63,0,6,5,0,

    // inputs:
    1,0,4,4,12,12,2,88,0, // button_1
    2,0,21,4,22,11,2,79,78,0,79,70,70,0, //switch_1
    1,0,79,3,12,12,2,88,0, // button_2
    2,0,4,23,22,11,2,79,78,0,79,70,70,0, //switch_2

    // outputs:
    65,4,50,5,9,9,2, // led_1
    66,1,65,3,7,16,2 // level_1
};

Notice how when the Editor generated this array and struct, the elements were sorted by category, but not by type (button_2 is after switch_1).


Why header bytes A, B and C-D = 4,2,63,0 ? Well, let's do some simple additions... The initial value of C is always 3, and the value of HF in this example, is 0b000. So:

  • Each Button takes one input and 9 bytes:
    A +=  2 = 2
    C += 18 = 21

  • Each Switch takes one input and 14 bytes:
    A +=  2 = 4
    C += 28 = 49

  • The LED takes one output and 7 bytes:
    B +=  1 = 1
    C +=  7 = 56

  • The Level takes one output and 7 bytes:
    B +=  1 = 2
    C +=  7 = 63

Nice, we have calculated our A, B, and C-D values!


We can rearrange the Elements by type, by moving their lines where we want, in both the array and the struct:

uint8_t RemoteXY_CONF[] =
{
    // Header:
    4,2,63,0,6,5,0,

    // Inputs:
    // Buttons
    1,0, 4,4,12,12,2,88,0, // button_1
    1,0,79,3,12,12,2,88,0, // button_2 
    // Switches
    2,0,21,4,22,11,2,79,78,0,79,70,70,0, // switch_1
    2,0,4,23,22,11,2,79,78,0,79,70,70,0, // switch_2

    // Outputs:
    // LEDs
    65,4,50,5,9,9,2, // led_1
    // Levels
    66,1,65,3,7,16,2 // level_1
};

// this structure defines all the variables of your control interface 
struct {

  // Inputs:
  // Buttons
  uint8_t button_1; // =1 if button pressed, else =0 
  uint8_t button_2; // =1 if button pressed, else =0 
  // Switches
  uint8_t switch_1; // =1 if switch ON and =0 if OFF
  uint8_t switch_2; // =1 if switch ON and =0 if OFF 

  // Outputs:
  // LEDs
  uint8_t led_1_r; // =0..255 LED Red brightness
  // Levels
  int8_t level_1; // =0..100 level position

  // other variable
  uint8_t connect_flag;  // =1 if wire connected, else =0 

} RemoteXY;

Why rearrange elements by type? Not only because it looks nicer. It allows to simplify your code by using arrays (with some limitations) in the struct:

struct {

  // Inputs:
  uint8_t buttons[2]; // =1 if button pressed, else =0 
  uint8_t switches[2]; // =1 if switch ON and =0 if OFF

  // Outputs:
  uint8_t led_1_r; // =0..255 LED Red brightness
  int8_t  level_1; // =0..100 level position

  // other variable
  uint8_t connect_flag;  // =1 if wire connected, else =0 

} RemoteXY;


Have fun wink

2

Re: Manual modification of the array

- Reserved -

More to come, maybe smile