docs/modbus_mapping_new_start_address.md

   1 # modbus_mapping_new_start_address
   2
   3 ## Name
   4
   5 modbus_mapping_new_start_address - allocate four arrays of bits and registers accessible from their starting addresses
   6
   7 ## Synopsis
   8
   9 ```c
  10 modbus_mapping_t* modbus_mapping_new_start_address(
  11     int start_bits, int nb_bits,
  12     int start_input_bits, int nb_input_bits,
  13     int start_registers, int nb_registers,
  14     int start_input_registers, int nb_input_registers);
  15 ```
  16
  17 ## Description
  18
  19 The `modbus_mapping_new_start_address()` function shall allocate four arrays to
  20 store bits, input bits, registers and inputs registers. The pointers are stored
  21 in *modbus_mapping_t* structure. All values of the arrays are initialized to zero.
  22
  23 The different starting addresses make it possible to place the mapping at any
  24 address in each address space. This way, you can give access to clients to
  25 values stored at high addresses without allocating memory from the address zero,
  26 for example to make available registers from 340 to 349, you can use:
  27
  28 ```c
  29 mb_mapping = modbus_mapping_new_start_address(0, 0, 0, 0, 340, 10, 0, 0);
  30 ```
  31
  32 The newly created `mb_mapping` will have the following arrays:
  33
  34 - `tab_bits` set to NULL
  35 - `tab_input_bits` set to NULL
  36 - `tab_registers` allocated to store 10 registers (`uint16_t`)
  37 - `tab_input_registers` set to NULL
  38
  39 The clients can read the first register by using the address 340 in its request.
  40 On the server side, you should use the first index of the array to set the value
  41 at this client address:
  42
  43 ```c
  44 mb_mapping->tab_registers[0] = 42;
  45 ```
  46
  47 If it isn't necessary to allocate an array for a specific type of data, you can
  48 pass the zero value in argument, the associated pointer will be NULL.
  49
  50 This function is convenient to handle requests in a Modbus server/slave.
  51
  52 ## Return value
  53
  54 The `modbus_mapping_new_start_address()` function shall return the new allocated structure if
  55 successful. Otherwise it shall return NULL and set errno.
  56
  57 ## Errors
  58
  59 - *ENOMEM*, not enough memory.
  60
  61 ## Example
  62
  63 ```c
  64 /* The first value of each array is accessible at the defined address.
  65 The end address is ADDRESS + NB - 1. */
  66 mb_mapping = modbus_mapping_new_start_address(
  67     BITS_ADDRESS, BITS_NB,
  68     INPUT_BITS_ADDRESS, INPUT_BITS_NB,
  69     REGISTERS_ADDRESS, REGISTERS_NB,
  70     INPUT_REGISTERS_ADDRESS, INPUT_REGISTERS_NB
  71 );
  72 if (mb_mapping == NULL) {
  73     fprintf(
  74         stderr, "Failed to allocate the mapping: %s\n",
  75         modbus_strerror(errno)
  76     );
  77     modbus_free(ctx);
  78     return -1;
  79 }
  80 ```
  81
  82 ## See also
  83
  84 - [modbus_mapping_new](modbus_mapping_new.md)
  85 - [modbus_mapping_free](modbus_mapping_free.md)