Programming with NanoJ

A NanoJ program receives computing time cyclically in a 1 ms clock (see following figure). Because computing time is lost through interrupts and system functions of the firmware, only approx. 30% – 50% of computing time is available to the user program (depending on control mode and application). In this time, the user program must run through the cycle and either complete the cycle or yield the computing time by calling the yield() function. In the former case, the user program is restarted with the start of the next 1 ms cycle; the latter results in the program being continued on the next 1 ms cycle with the command that follows the yield() function.

If the NanoJ program needs more time than was allotted, it is ended and an error code set in the object dictionary.

A NanoJ program has a number of possibilities for communicating with the controller:

• Read and write OD values using PDO mapping
• Directly read and write OD values via NanoJ functions
• Call other NanoJ functions (e.g., write debug output)

The OD values of the user program are made available in the form of variables via PDO mapping. Before a user program receives the 1 ms time slot, the firmware transfers the values from the object dictionary to the variables of the user program. As soon as the user program receives computing time, it can manipulate these variables as regular C variables. At the end of the time slot, the new values are then automatically copied by the firmware back to the respective OD entries.

To optimize the performance, three types of mapping are defined: input, output, and input/output (In, Out, InOut).

• Input mappings can only be read; they are not transferred back to the object dictionary.
• Output mappings can only be written.
• Input/output mappings, on the other hand, can both be read and written.

The set mappings can be read and checked via the GUI for objects 2310_h, 2320_h, and 2330_h. Up to 16 entries are allowed for each mapping.

Whether a variable is stored in the input, output or data range is controlled in Plug & Drive Studio via the specification of the linker section.

When executing a cycle, the NanoJ program essentially consists of the following three steps with respect to the PDO mapping:

1. Read values from the object dictionary and copy them to the input and output areas
2. Execute a user program
3. Copy values from the output and input areas back to the object dictionary

The configuration of the copy processes is based on the CANopen standard.

In addition, values of the object dictionary can be accessed via NanoJ functions. This is generally slower; mappings are therefore to be preferred. The number of mappings is limited (16 entries each in In/Out/InOut).

A list of available NanoJ functions can be found in chapter NanoJ functions in the NanoJ program.

A user program consists of at least two instructions:

• the preprocessor instruction #include "wrapper.h"
• the void user(){} function

The code to be executed can be stored in the void user() function.

Examples:

The global variable is to be initialized within the void user() function:

unsigned int i; 
void user(){
 i = 1;
 i += 1; 
} 

The following assignment results in an error during compilation:

unsigned int i = 1;
 void user() {
 i += 1; 
} 

The example shows the programming of a square wave signal in object 2500_h:01_h.

// file main.cpp
map S32 outputReg1 as inout 0x2500:1
#include "wrapper.h"

// user program
void user()
{
  U16 counter = 0;
  while( 1 ) 
  {
    ++counter; 

    if( counter < 100 )
     InOut.outputReg1 = 0;
    else if( counter < 200 )
      InOut.outputReg1 = 1;
    else
      counter = 0;

    // yield() 5 times (delay 5ms)
    for(U08 i = 0; i < 5; ++i )
      yield();
  }
}// eof

You can find other examples at us.nanotec.com.

The declaration of the mapping is structured as follows:

map <TYPE> <NAME> as <input|output|inout> <INDEX>:<SUBINDEX>

Where:

• <TYPE> 

  The data type of the variable; U32, U16, U08, S32, S16 or S08.

• <NAME>

  The name of the variable as it is used in the user program.

• <input|output|inout> 

  The read and write permission of a variable: a variable can be declared as an input, output or inout. This defines whether a variable is readable (input), writable (output) or both (inout) and the structure by means of which it must be addressed in the program.

• <INDEX>:<SUBINDEX> 

  Index and subindex of the object to be mapped in the object dictionary.

Each declared variable is addressed in the user program via one of the three structures: In, Out or InOut depending on the defined write and read direction.

Example of a mapping and the corresponding variable accesses:

// 6040h:00h is UNSIGNED16 
map U16 controlWord as output 0x6040:00
// 6041h:00h is UNSIGNED16
map U16 statusWord as input 0x6041:00

// 6060h:00h is SIGNED08 (INTEGER8)
map S08 modeOfOperation as inout 0x6060:00

#include "wrapper.h"

void user()
{
  [...]
  Out.controlWord = 1;
  U16 tmpVar = In.statusword;
  InOut.modeOfOperation = tmpVar;
  [...]
}

A possible source of errors is a write access with the od_write() function (see NanoJ functions in the NanoJ program) of an object in the object dictionary that was simultaneously created as mapping. The code listed in the following is incorrect:

map U16 controlWord as output 0x6040:00
#include " wrapper.h"
void user()
{
 [...]
  Out.controlWord = 1;
  [...]
  od_write(0x6040, 0x00, 5 ); // der Wert wird durch das Mapping überschrieben
  [...]
}

The line with the od_write(0x6040, 0x00, 5 ); command has no effect. As described in the introduction, all mappings are copied to the object dictionary at the end of each millisecond.

This results in the following sequence:

1. The od_write function writes the value 5 in object 6040_h:00_h.
2. At the end of the 1 ms cycle, the mapping is written that also specifies object 6040_h:00_h, however, with the value 1.
3. From the perspective of the user, the od_write command thus serves no purpose.

void od_write (U32 index, U32 subindex, U32 value)

This function writes the transferred value to the specified location in the object dictionary.

U32 od_read (U32 index, U32 subindex)

This function reads the value at the specified location in the object dictionary and returns it.

while (od_read(2400,2) != 0) // wait until 2400:2 is set
{ yield(); }

void yield() 

This function returns the processor time to the operating system. In the next time slot, the program continues at the location after the call.

void sleep (U32 ms)

This function returns the processor time to the operating system for the specified number of milliseconds. The user program is then continued at the location after the call.

The following functions output a value in the debug console. They differ with respect to the data type of the parameter to be passed.

bool VmmDebugOutputString (const char *outstring)

bool VmmDebugOutputInt (const U32 val)

bool VmmDebugOutputByte (const U08 val)

bool VmmDebugOutputHalfWord (const U16 val)

bool VmmDebugOutputWord (const U32 val) 

bool VmmDebugOutputFloat (const float val) 

If the buffer is full, VmmDebugOutputxxx() initially fails; execution of the user program ceases and it stops at the location of the debug output. Only after the GUI has read the buffer and after subindex 00 has been reset does the program continue and VmmDebugOutputxxx() returns to the user program.