### [ На русском ] ↔ [ English ]

- Sketch Variables
- Displaying Variables
- Setting Values
- Number Conversion

## ⇮SKETCH VARIABLES: REGISTRATION

ESPShell provides an API to register and manipulate sketch variables. Supported types are limited to simple C types such as unsigned/signed int, char, short, float, and generic void* pointers. Arrays of these basic types are also supported.

To make a variable accessible from ESPShell, it must be registered.

Use the convar_add() macro to register a variable. There are also specialized macros like convar_addp() for pointers and convar_adda() for arrays.

Example usage in an Arduino sketch: suppose we have three variables we want to expose to the shell:

      static int some_variable;
      unsigned char *pointer;
      char array[10];

      void setup() {
        ...
        convar_add(some_variable); ← Register a simple variable
        convar_addp(pointer);      ← Register a pointer
        convar_adda(array);        ← Register an array
        ...
      }

Other available macros include: convar_addap(Name) - to register an array of pointers, and convar_addpp(Name) - to register a pointer to a pointer.

## ⇮DISPLAYING VARIABLES AND VALUES

The code snippet above registers three variable types: an integer, a pointer, and an array. Once registered using the appropriate convar_addX() macros, these variables can be accessed via the shell using the commands var NAME and show memory ADDRESS.

When executed without arguments, the var command lists all registered variables:

        esp32#>var
        % Sketch variables:
        % Variable X name | sizeof(X) |     typeof(X)    |     Value
        %-----------------+-----------+------------------+----------------
        %           table |         4 |            int * |       0x3ffbdb88
        %              a4 |         4 |          float * |       0x3ffbdbb4
        %              a3 |         4 |            float |        10.000000
        %              a2 |         4 |     unsigned int |                0
        %              a1 |         1 |    unsigned char |               99
        %              a0 |         4 |              int |              -99
        %     tbl_min_len |         2 |   unsigned short |               16
        %       bypass_qm |         4 |              int |                0
        %       pcnt_unit |         4 |              int |                0
        %    pcnt_channel |         4 |              int |                0
        %ls_show_dir_size |         4 |              int |                1
        esp32#>

Note that for pointers and arrays, their address is shown rather than the content. To dereference a pointer or view array contents, use var VAR_NAME:

        esp32#>var a4
        % float * a4 = 0x3ffbdbb4;  // Pointer to a 4-byte memory region
        % a4[1] = {
        %    10.000000, // a4[0]
        % };

Another example:

        esp32#>var table
        % int * table = 0x3ffbdb88;  // Array of 10 elements (4 bytes each)
        % int table[10] = {
        %    1, // table[0]
        %    2, // table[1]
        %    3, // table[2]
        %    4, // table[3]
        %    5, // table[4]
        %    6, // table[5]
        %    7, // table[6]
        %    8, // table[7]
        %    9, // table[8]
        %    0, // table[9]
        % };

To access a specific array element, use an index, just like in C:

        esp32#>var table[5]
        % int table[5] = 6;
        esp32#>

This syntax can also be used to access memory pointed to by a pointer. When using an index on a pointer variable, ESPShell will display a warning, as it cannot determine valid memory bounds.

Here's another example of displaying a variable:

        esp32#>var a1
        % unsigned char a1 = 99;
        esp32#>

## ⇮SETTING VARIABLE VALUES

To change a variable's value, use the command var VARIABLE_NAME NEW_VALUE. For example, to change `a1` to 88:

        esp32#>var a1 88
        esp32#>var a1
        % unsigned char a1 = 88;  // Use "var 88" to view this number in hex, octal, binary, etc.
        esp32#>

Some basic type checks are enforced. For example, you cannot assign a signed value to an unsigned variable or a floating-point value to an integer. Array values cannot be changed this way, as their address is fixed by the linker and cannot be modified at runtime.

## ⇮NUMBER BASE CONVERSION

Another use of the var command is number base conversion. If the argument passed to var is a number (decimal, hexadecimal, floating point, octal, or binary), ESPShell will display the value in multiple bases and perform an unsafe C-style memory cast. This is mainly useful to inspect how negative or floating-point numbers are represented in memory.

Example:

        esp32#>var 666
        % "666" is a number, represented as:
        % C-style memory cast:
        % unsigned : 666
        %   signed : 666
        % float    : 0.000000
        % In different bases:
        % Hex      : 0x29a
        % Octal    : 01232
        % Binary   : 0b1010011010
        esp32#>

Or:

        esp32#>var 666.666
        % "666.666" is a number, represented as:
        % C-style memory cast:
        % unsigned : 1143384736
        %   signed : 1143384736
        % float    : 666.666016
        % In different bases:
        % Hex      : 0x4426aaa0
        % Octal    : 010411525240
        % Binary   : 0b1000100001001101010101010100000
        esp32#>

Or:

        esp32#>var 0b111
        % "0b111" is a number, represented as:
        % C-style memory cast:
        % unsigned : 7
        %   signed : 7
        % float    : 0.000000
        % In different bases:
        % Hex      : 0x7
        % Octal    : 07
        % Binary   : 0b111
        esp32#>