Porting Manual

1. Overview

Adaptation of emb6 to its working environment is done via a number of ports. A simple one of which is to interface with applications. More complicated might be ports to platforms, including MCU and radio transceiver, which require additional testing, validation and optimization. Therefore, it is recommended for developers to begin with having a good insights into structure of emb6 building system, which is automated based on SCons and described in detail here.

The following sections describe requirements and give tips for developers.

2. Ports to applications

Implementers, who desires to create new ports, shall first check some example ports that are included in the emb6 repository in the directory root/demo.

2.1. Create new applications under root/demo directory. Implementation of the applications shall provide following API functions:

/**
 * @brief   Initialize demo application
 *
 * @retval  0 when successful, otherwise -1 
 */
int8_t demo_<app_name>_init (void);

/**
 * @brief  Configure demo application
 *
 * @param[in]  p_netstack  Pointer to a variable holidng netstack structure 
 * @retval  0 when successful, otherwise -1 
 */
int8_t demo_<app_name>_config (s_ns_t *p_netstack);

2.2. Add the application to the common main implementation under root/demo where its API functions are placed as following:

/**
 * @brief  Local demo appliction configuration function
 *
 * @param[in]  p_netstack  Point to a variable holidng netstack structure 
 * @param[out] p_err       Point to variable holding return error code
 * @retval  none
 */
static void loc_demoAppsConf (s_ns_t *p_netstack, e_nsErr_t *p_err)
{
  /* set return error code to default */
  *p_err = NETSTK_ERR_NONE;

  /* configure demo application */
  if (demo_<app_name>_config (p_netstack) != 0) {
    *p_err = NETSTK_ERR_FATAL;
  }
}

/**
 * @brief  Local demo appliction initialization function
 *
 * @retval     0 when successful, otherwise 1
 */
static uint8_t loc_demoAppsInit (void)
{
  if(demo_<app_name>_init() == 0) {
    return 0;
  }

  return 1;
}

2.3. Create SConsript in accordance with the application. The SConscript shall specify what modules of emb6 and symbol definitions the application requires. Information on variables indicating emb6 modules is provided by the SConscript (6), see here.

2.4. Define a new variable indicating the application in targets.scons using this format <app_name> = ('path', 'to', 'the', 'application'). For example following code defines a variable named coap_srv, which indicates CoAP server demo application, and its value specifies where implementation of the demo application and its SConscript file can be found i.e. root/demo/coap/server.

coap_srv = ('coap', 'server')

2.5. Build the application. When the application is desired to use, one shall create a new target description whose assign application configuration attribute is set to the variable indicating the application. For instance, target description below indicates that the demo application named <app_name> is desired to run on platform using MCU efm32lg990f256 with radio transceiver TI cc112x.

trg += [{
    'id'        : '<app_name>_efm32lg990f256_cc112x',
    'apps_conf' : [ <app_name> ],
    'bsp'       : get_descr(bsp, 'efm32lg990f256_cc112x')
}]

3. Ports to radio transceiver

Anyone who creates a port to a radio transceiver shall have a look at the example ports in the following directory root/target/if. Below requirements should be met:

3.1. Transceiver driver shall have the common API function signalling defined in emb6.h, see here.

3.2. The transceiver driver implementation shall interface with BSP API functions in order to be hardware-independent.

3.3. Transceiver driver variable is globally declared in emb6.h, for example:

extern  const s_nsRF_t      RFDrvCC112x;

3.4. Implementation of radio transceiver driver is placed under root/target/if/<transceiver_name>, for example

root
|-- target
    |-- if
        |-- cc112x

4. Ports to microprocessor

Anyone who creates a port to a microprocessor shall have a look at the example ports in the following directory root/target/arch. Below steps shall be followed:

4.1. Implementations of the microprocessor peripherals

Ihe implementation shall be organized in following structure:

root
|-- target
    |-- arch
        |-- <arch_name>
            |-- <mcu_name>
                |-- <vendor_name>
                    |-- toolchain
                        |-- <compiler_name>

4.2. Create supporting SConscripts

Appropriate SConscripts (7) and (8) as described in see here shall be provided according to the microprocessor.

4.3. Provide HAL implementation

A HAL implementation of the mircoprocessor shall be provided under folder target/mcu/<mcu_name> and use the emb6-specific API functions declared in target.h

5. Ports to platform

A detailed description and example on ports to a new platform is provided in section "Add support for a new platform" in chapter Building emb6 with SCons.