Skip to content

Setup calibration mode#

When dealing with analog values, there is often a calibration of the hardware required to achieve the best accuracy. This example situation is a good reason for implementing a manufacturer-specific factory area.

Example Goal#

The example focus is the user object for CAN triggered write access to a manufacturer-specific area.

Object Type Idea#

The main idea is a collection of object entries, which are writable after a simple identification mechanism.

For a tiny use-case we assume to achieve a simple calibration mechanism. The application uses the calibration values to transform input values with a formula:

adcValue = (adcRaw * calFactor) / calDivisor + calOffset;

Object Entry Definitions#

We define some manufacturer specific entries in the object dictionary:

Index Subindex Type Access Value Description
2F00h 0 UNSIGNED32 Const 4 Max. Subindex
2F00h 1 UNSIGNED32 Write Only 0 Calibration Key
2F00h 2 SIGNED32 Read Write 1 Cal. Factor
2F09h 3 SIGNED32 Read Write 1 Cal. Divisor
2F00h 4 SIGNED32 Read Write 0 Cal. Offset

To achieve the permanent calibration after setting the values, the subindex 2 to 4 must be storable in NVM.

The Number of Entries is a constant, which is read-only for the CAN network and conforms to the standard way of defining subindex 0 of an array.

The key to get the wanted functionality is the entry at subindex 1. This object entry accepts write access of a calibration key value. With the correct key, this operation enables the write access to the other calibration object entries from subindex 2 to 4. A wrong key disables the write access.

Implement Object Type#

Lets implement the calibration user type as shown in the CANopen Usage: User Object:

uint8_t calWriteAllowed = 0u;

const CO_OBJ_TYPE COTCal = { 0, 0, 0, CalWrite };

#define CO_TCAL ((CO_OBJ_TYPE*)&COTCal)

The write function is called when the CAN network writes to the related object entry via SDO request. We typically send an error, because the calibration data is read-only per default:

int16_t CalWrite(CO_OBJ *obj, struct CO_NODE_T *node, void *buf, uint32_t size)
{
  /* indicate an write error */
  return CO_ERR_TYPE_WR;
}

Now we want to change this function to enable the write access for the calibration values after a secret key-value is written to the object entry at subindex 1.

#define CAL_KEY 0x1f3c7a3b      /* a random value for enabling write access */

int16_t CalWrite(CO_OBJ *obj, struct CO_NODE_T *node, void *buf, uint32_t size)
{
  uint32_t value  = *((uint32_t *)buf);
  CO_ERR   result = CO_ERR_TYPE_WR;
  uint8_t  subidx = CO_GET_SUB(obj->Key);

  if (subidx == 1u) {
    if (value == CAL_KEY) {
      calWriteAllowed = 1u;
    } else {
      calWriteAllowed = 0u;
    }
    result = 0u;
  } else {
    if ((subidx          != 0u) &&
        (calWriteAllowed == 1u)) {
      *(int32_t *)obj->Data = value;
      result = 0u;
    }
  }
  return result;
}

Implement Object Entries#

Parameter Handling#

First, we need to get a memory area for our calibration data. We get this area by creating a structure with the calibration data values:

struct CAL_MEM_T {
  int32_t Factor;
  int32_t Divisor;
  int32_t  Offset;
};

struct CAL_MEM_T CalDefaults = {
  (int32_t)1u,  /* factor  */
  (int32_t)1u,  /* divisor */
  (int32_t)0u   /* offset  */
};
struct CAL_MEM_T CalValue;

For store and restore operations, the parameter group control structure specifies the memory area and the reset type of these parameters:

const CO_PARA CalParaObj = {
  0L,                            /* placement in non-volatile memory */
  sizeof(struct CAL_MEM_T),      /* size of parameter memory         */
  (uint8_t*)&CalValue,           /* start address of parameter mem   */
  (uint8_t*)&CalDefaults,        /* start address of default para.   */
  CO_RESET_NODE,                 /* reset type for reload parameter  */
  (void*)"Calibration",          /* user parameter identification    */
  CO_PARA___E                    /* enable parameter storage on cmd  */
};

Finally, in the standard parameter store/restore entries, we use a separate subindex for the calibration values (for example: subindex #2):

const CO_OBJ ExampleObjDir[] = {
    :
  { CO_KEY(0x1010, 2, CO_OBJ_____RW), CO_TPARA_STORE, (CO_DATA)(&CalParaObj) },
    :
};

Calibration Object Entry#

We use our user type to define the calibration object entry:

const CO_OBJ ExampleObjDir[] = {
    :
  { CO_KEY(0x2F00, 0, CO_OBJ_D___RW), CO_TUNSIGNED8, (CO_DATA)(4u) },
  { CO_KEY(0x2F00, 1, CO_OBJ_D____W), CO_TCAL,       (CO_DATA)(0u) },
  { CO_KEY(0x2F00, 2, CO_OBJ_____RW), CO_TCAL,       (CO_DATA)(&CalValue.Factor) },
  { CO_KEY(0x2F00, 3, CO_OBJ_____RW), CO_TCAL,       (CO_DATA)(&CalValue.Divisor) },
  { CO_KEY(0x2F00, 4, CO_OBJ_____RW), CO_TCAL,       (CO_DATA)(&CalValue.Offset) },
    :
};

Well, that's it. Now we have an (unsecured) protected calibration area for manufacturer-specific data. This concept is a starting point for more secure solutions with advanced algorithms.