YAMI4 with TI-RTOS on MSP-EXP432E401Y

The Code Composer Studio facilitates development of user applications by providing a wide range of example programs for each supported hardware platform - these example programs can be used as starting points for custom programs. The YAMI4 libraries can be added to the CCS workspace and integrated with already existing projects. The two YAMI4 components are the core library, which provides basic messaging services, and the general-purpose C++ library, which supports higher-level messaging patterns on top of the core library.
The idea presented here relies on the tcpEcho example project as a starting point, because it already provides most of the configuration settings related to networking. The tcpEcho example can be installed from the Resource Explorer:

In order to avoid conflicts with accidental re-installation of this example, the tcpEcho project can be renamed - this article uses the name myProgram as the actual application name after such name change.

Even though this choice is purely arbitrary, the following relies on the assumption that the YAMI4 distribution package was unpacked directly in the workspace directory - that is, as a sibling to the myProgram project directory. The YAMI4 package contains two projects already prepared for import into CCS:

• src/core/tirtos/YAMI4-SimpleLink-core
• src/cpp/tirtos/YAMI4-SimpleLink-cpp

These two projects should be imported into the CCS workspace:

Above, YAMI4-SimpleLink-core and YAMI4-SimpleLink-cpp are library projects and myProgram is the actual application program that directly relies on the general-purpose C++ library, as well as on TI-RTOS and NDK, by means of its project product dependencies (these are automatically imported from the original tcpEcho example). The last project seen above, tirtos-builds_..., is a dependent common project that is automatically contributed by the tcpEcho example.

Once the project skeleton is imported and put together with the YAMI4 libraries in a single workspace, the more detailed look at the application project structure is:

There are multiple files in the myProgram project, but the ones that are of direct interest to the developer are:

• main_tirtos.c - from the original example project, contains the main() function; this function will be modified to invoke the actual application code, conveniently put in a separate file to minimize the conflicts when the code is re-imported,
• publisher.cpp - an example file from the YAMI4 package, from the src/cpp/tirtos/examples/subscription directory; this file contains the actual code that relies on YAMI4 to provide the actual functionality - it is intentionally kept separate from the main_tirtos.c file to avoid conflicts with re-imported code and to allow direct use of C++.
• tcpecho.syscfg and release.cfg (from tirtos_builds) - the configuration files, from the original example project; these files will need to be slightly modified to properly run the final program.

Note that the original files tcpEcho.c and tcpEchoHooks.c were removed from the myProgram project.

The application relies on both YAMI4 libraries and even though it is not necessary, this is clearly expressed as project dependencies, so that modifications in any of the parts are always properly synchronized and taken into account in final builds.

Having the workspace and file structure in place, the following options need to be considered to properly tie together all involved projects.

For the YAMI4 Core library:

The device setting above just reflects the choice of target device. All options here have default values.

The setting above relates to the include paths and in addition to the first two, which are contributed by the YAMI4 core library itself, the remaining ones refer to the TI-RTOS system and its components. The version numbers in these paths reflect the actual packages that were automatically installed by CCS together with the original example program and are likely to change with future SDK updates.

The YAMI4_WITH_TIRTOS and YAMI4_WITH_TI_SIMPLELINK pre-processor symbols need to be defined for both YAMI4 libraries and for the final application as well.

The language settings - the YAMI4 Core library does not use exceptions or RTTI, but calls back into higher levels that do, so they need to be enabled (this should be also set for the other projects).

With all the options set appropriately, the YAMI4 Core library project should involve all these source files from the YAMI4 distribution package:

• src/core/*.cpp - these are platform-neutral implementations of the core messaging functions,
• src/core/tirtos/*.cpp - these are files specific to TI-RTOS and NDK that provide the system abstraction layer for the rest of the core library.

Settings for the YAMI4-SimpleLink-cpp library project should be similar, except for the include directories:

Similarly to the core part, the YAMI4 C++ library project should refer to the following sources from the YAMI4 distribution package:

• src/cpp/*.cpp - these are platform-neutral implementations of the high-level messaging functions,
• src/cpp/tirtos/*.cpp - these are specific to TI-RTOS.

Finally, for the actual myProgram application, include paths and the set of dependent library files:

Apart from the project settings described above, two files need to be modified in order to properly integrate together all components.

The tcpecho.syscfg file needs to be modified slightly - the following lines should be commented out (or removed):

//General.networkIPAddrHook = "netIPAddrHook";
//General.serviceReportHook = "serviceReportHook";

At the same time, the following lines should be added to ensure static IP configuration (the addresses of course relate to the particular networking environment and need not be static, NDK can also work with DHCP):

General.networkOpenHook = "netOpenHook";
General.localIPAddrConfig = "Enable Static IP Address";
General.staticIPAddr = "192.168.11.112";
General.gatewayIpAddr = "192.168.11.254";

The release.cfg file (in the tirtos_builds_... project) needs to be modified, too - the heap size needs to be increased to allow meaningful messaging (the default size of 1024 is certainly too small):

Memory.defaultHeapSize = 32768;

The whole main_tirtos.c file can be replaced with the following content:

#include <stdint.h>
#include <ti/net/slnet.h>
#include <ti/sysbios/BIOS.h>
#include <ti/sysbios/knl/Task.h>

#include <ti/drivers/Board.h>

#define TASKSTACKSIZE 2048
Task_Struct taskStruct;
Char taskStack[TASKSTACKSIZE];

Void run_publisher(UArg arg0, UArg arg1);

void netOpenHook()
{
    Task_Params taskParams;

    (void)ti_net_SlNet_initConfig();

    Task_Params_init(&taskParams);
    taskParams.stackSize = TASKSTACKSIZE;
    taskParams.stack = &taskStack;
    Task_construct(&taskStruct, &run_publisher, &taskParams, NULL);
}

extern void ti_ndk_config_Global_startupFxn();

int main(void)
{
    Board_init();

    ti_ndk_config_Global_startupFxn();

    BIOS_start();
}

The main function initializes the hardware and software components according to the config settings and starts an actual application task in the network set-up hook to ensure that the program operation is performed with the network adapter already in the proper state. The name of the hook, netOpenHook was selected above in the configuration file.

An important part of this code is the invocation of the actual publisher program - the run_publisher function is declared and then called as a task function from netOpenHook, which is called automatically when the network is set up. The run_publisher function is implemented in a separate file publisher.cpp, included in the set of YAMI4 examples.

The subscription example is the most elaborate in the YAMI4 distribution package, because the publisher program acts both as a server (accepts subscription requests from clients) and as a client (sends a stream of data updates to subscribers).

One of the main design goals of YAMI4 is to be composable and non-intrusive with regard to its application in the target program. These goals mean in particular that YAMI4 should not hijack the environment and it should not assume that it is the only user of some resource, like a memory space or a network stack. These goals are straightforward on a POSIX or Windows system, where system resources are managed outside of the user code, but in RTOS it is the user code that decides when and how the environment is set up. In order not to interfere with the policies of the user code:

• the YAMI4 agent does not create any new threads for its needs and instead allows the user to provide the thread of execution for the worker and dispatcher(s).

This approach allows the user retain complete control over when and how these critical system resources are created, which includes decisions like whether resources are allocated statically or dynamically or what should be the task priorities or their stack sizes. See the example programs (like the complete content of the publisher.cpp presented above) to check how the user code can provide the necessary resources to the YAMI4 agent.