control - northern-bites/nbites GitHub Wiki

This document refers to man/control and is intended to aid in defining new control functions and calling them from the java nbtool.

The first step in defining a control function is to implement a c++ function with prototype

uint32_t functionName(Log * arg)

The arg argument of the function will be the Log object which was sent to robot to call your function (more on this later).

Next, you need to add your function to the function map created in init_fmap(). The string key here is the name by which you will identify the function from nbtool.

---

On the java side, calling a man control function is a simple as creating a special 'command' Log and giving it to a ControlInstance.

To obtain a ControlInstance, you can either call ControlIO.create() with a robot's address, or call one of the ControlIO.getByX() methods. ControlIO.getByIndex(0) will probably suffice – it returns the first (often only) control instance currently connected or null if no such instance exists.

The command log is given to a control instance by calling tryAddCmnd(). While the log's data field is entirely up to you, the log's SExpr tree follows a slightly different format than traditional 'nblog logs'. The first node of the log's top level list must be 'command'. The second node must be an atom with value equal to the string identifier of the control function you wish to call on the robot. See createCmndSetFlag() and createCmndTest() in ControlIO.java.

The rest of the log – tree and data – is entirely up to you. You may assume whatever SExprs or data you attach to the log will be present when your man-side control function is called with the log as an argument.

Do not delete the command log argument in your man-side control function – the control server will do this for you. Consequently, you must copy all data you need from the command log before your control function returns.