Skip to end of metadata
Go to start of metadata

The last step in making your network interface active on the network is to start it. Similar to the Add function, each type of network interface has its own Start function.

Each Start function has an optional argument for a setup structure that includes parameters for IPv4, IPv6, DHCP and other interface-specific parameters. This allows your application to define and populate a setup structure with parameters that match your network's characteristics and your application's needs. Including the argument causes the Network Core Stack to perform the minimal setup required for the interface to be visible on the network. For more details on the network interface setup structure, see Network Interface Start Setup.

The sections below show how to start a network interface according to its type; either Ethernet of Wi-Fi.

Starting the Network Interface

Ethernet Interface

Listing - Example of call to NetIF_Ether_Start() shows an example of call to NetIF_Ether_Start().

For more information on configuring arguments to pass to NetIF_Ether_Start(), see Network Interface Start Setup.

For a complete example on how to start an Ethernet interface, please refer to the example files. 

static  const  NET_IF_ETHER_CFG  Ex_NetIF_CfgDflt = {
        .HW_AddrStr                    = "00:17:4A:B0:00:01",
        .IPv4.Static.Addr              = DEF_NULL,
        .IPv4.Static.Mask              = DEF_NULL,
        .IPv4.Static.Gateway           = DEF_NULL,
        .IPv4.DHCPc.En                 = DEF_YES,
        .IPv4.DHCPc.Cfg                = DHCPc_CFG_DFLT,
        .IPv4.DHCPc.OnCompleteHook     = Ex_DHCPc_SetupResult,
        .IPv4.LinkLocal.En             = DEF_NO,
        .IPv4.LinkLocal.OnCompleteHook = DEF_NULL,
        .IPv6.Static.Addr              = DEF_NULL,
        .IPv6.Static.PrefixLen         = 0,
        .IPv6.Static.DAD_En            = DEF_NO,
        .IPv6.AutoCfg.En               = DEF_YES,
        .IPv6.AutoCfg.DAD_En           = DEF_YES,
        .IPv6.Hook                     = Ex_IPv6_AddrCfgResult
};

NET_IF_ETHER_CFG  if_cfg;
NET_IF_NBR        if_nbr;
RTOS_ERR          err;


if_cfg = Ex_NetIF_CfgDflt;

                                                       /* ------------- START ETHERNET INTERFACE ------------- */
NetIF_Ether_Start(if_nbr, &if_cfg, &err);
if (err.Code != RTOS_ERR_NONE) {
    /* An error occured. Error handling should be added here. */
}
Listing - Example of call to NetIF_Ether_Start()

Wi-Fi Interface

Listing - Example of call to NetIF_WiFi_Start() shows an example of call to NetIF_WiFi_Start().

For more information on configuring arguments to pass to NetIF_WiFi_Start(), see Network Interface Start Setup.

For a complete example on how to start a Wi-Fi Interface, please refer to the example files. 

static  const  NET_IF_WiFi_CFG  Ex_NetIF_CfgDflt = {
        .HW_AddrStr                    = "00:17:4A:B0:00:01",
        .IPv4.Static.Addr              = DEF_NULL,
        .IPv4.Static.Mask              = DEF_NULL,
        .IPv4.Static.Gateway           = DEF_NULL,
        .IPv4.DHCPc.En                 = DEF_YES,
        .IPv4.DHCPc.Cfg                = DHCPc_CFG_DFLT,
        .IPv4.DHCPc.OnCompleteHook     = Ex_DHCPc_SetupResult,
        .IPv4.LinkLocal.En             = DEF_NO,
        .IPv4.LinkLocal.OnCompleteHook = DEF_NULL,
        .IPv6.Static.Addr              = DEF_NULL,
        .IPv6.Static.PrefixLen         = 0,
        .IPv6.Static.DAD_En            = DEF_NO,
        .IPv6.AutoCfg.En               = DEF_YES,
        .IPv6.AutoCfg.DAD_En           = DEF_YES,
        .IPv6.Hook                     = Ex_IPv6_AddrCfgResult,
        .Band                          = NET_DEV_BAND_2_4_GHZ
};

NET_IF_WIFI_CFG  if_cfg;
NET_IF_NBR       if_nbr;
RTOS_ERR         err;


if_cfg = Ex_NetIF_CfgDflt;

                                                      /* ------------- START WIRELESS INTERFACE ------------- */
NetIF_WiFi_Start(if_nbr, &if_cfg, &err);
if (err.Code != RTOS_ERR_NONE) {
    /* An error occured. Error handling should be added here. */
}
Listing - Example of call to NetIF_WiFi_Start()

Network Interface Ready

Because the network interface start function doesn't block, other mechanisms exist to let your application know when the setup of the interface is complete. You can use the different callback functions (DHCP, IPv6, IPv4. Link-Local) inside the NET_IF_xxx_CFG structure you are passing to the interface start function. You can use those callbacks to notify your application when a specific setup process has finished. They will also give you information on the process that just completed: for example, the status of the process, the IP address that was just configured, etc.

Micrium OS also includes a module to that allows your application to wait for the network interface setup to be complete. To enable this module, you must enable the NET_IF_CFG_WAIT_SETUP_READY_EN configuration in your net_cfg.h file (see section Network Core Compile-Time Configurations). So once the network interface is started, your application can begin waiting for the setup to be complete by using the API function NetIF_WaitSetupReady(). This function will wait for the various processes that you enabled in the NET_IF_xxx_CFG argument (DHCP, IPv6, etc.), and it will exit when every process has finished, if no error occurred. You can also pass a reference to a NET_IF_APP_INFO type variable. The function will populate structure with the information collected during the setup.

Starting the Network Interface Without a Configuration

Alternatively, the network interface can be started immediately without a configuration.

NET_IF_NBR       if_nbr;
RTOS_ERR         err;


                                                       /* ------------- START ETHERNET INTERFACE ------------- */
NetIF_Ether_Start(if_nbr, DEF_NULL, &err);
if (err.Code != RTOS_ERR_NONE) {
    /* An error occured. Error handling should be added here. */
}
Listing - Starting the interface without a configuration

Note that in this case, the interface setup must be done by calling the appropriate API functions after the interface has been started:

FunctionDescriptionSection in the Network Core Programming Guide
NetIPv4_CfgAddrAdd()Set a static IPv4 address on the network interface.IPv4 - Assign an Address to a Network Interface
DHCPc_IF_Add()Enable the DHCP client (IPv4) on the network interface.DHCP Client Programming
NetIPv4_AddrLinkLocalCfg()Enable the IPv4 Link-Local address setup on the network interface.IPv4 - Link-Local Address Setup
NetIPv6_AddrAutoCfgEn()Enable the IPv6 SLAAC setup on the network interface.IPv6 - Stateless Address Autoconfiguration (SLAAC)
NetIPv6_CfgAddrAdd()Set a static IPv6 address on the network interface.IPv6 - Assign an Address to a Network Interface
  • No labels