NT4 Client

Features

• Connects to Network Tables 4.0 servers
• Able to:
  • Subscribe to topics
  • Publish topics
  • Retrieve boolean, numeric, and string values off the server
  • Set boolean, numeric, and string values to the server

Installation

1. Drop the NT4Client directory into your project
2. Include NT4Client/NT4.h in your project source files
3. If you're not using CMake, link NT4Client/libNT4Client.a manually
4. If you are using CMake follow the instructions below

CMake addition

# Replace "${CMAKE_SOURCE_DIR}/NT4Client" with the location of your NT4Client directory
list(APPEND CMAKE_PREFIX_PATH "${CMAKE_SOURCE_DIR}/NT4Client")
find_package(NT4Client REQUIRED)

Usage

Creating and destroying the client

Creating the client:

// NT4_Connect takes in (<Host location>, <Client name>)
NT4Client client = NT4_Connect("192.168.0.1", "Test Client");
if(!client) /* Handle the error */

Destroying the client:

NT4_Close(client);

Note that all unclosed clients will automatically be closed for you when the program exits (atexit) so this is purely optional

Getting values

The first step when trying to retrieve values from NT4 is to subscribe to the topic. To do that, you must know the name of the topic and its type on the server. Subscribing will wait for the server to send an announce message back.

// NT4_Subscribe takes in (<Client>, <Topic name>)
if(!NT4_Subscribe(client, "/SmartDashboard/Example Topic") /* Handle errors */

Then, you can get the values off the server:

bool exampleTopic = NT4_GetBoolean(client, "/SmartDashboard/Example Topic");

Note that you have to use the proper typed function (NT4_GetBoolean, NT4_GetNumber, NT4_GetString). If you need to get a topic's type, you can use NT4_GetTopicType.

Bulk subscribing

// NT4_SubscribeToAll takes in (<Client>, <Prefix>)
// If the prefix is NULL, the client will subscribe to all available topics (the prefix is set to "/")
if(!NT4_SubscribeToAll(client, "/SmartDashboard/")) /* Handle errors */

Note that this function doesn't wait for the server to send back acknowledge messages. The client can't predict how many topics start with the specified prefix, so it just updates the local registry as more topic come in.

Putting values onto the server

First, you must publish your topic. Publishing (like subscribing) will wait for the server to send an announce message back.

// NT4_Publish takes in (<Client>, <Topic name>, <Topic type>)
if(!NT4_Publish(client, "/SmartDashboard/Example Published Topic", NT4Type.STRING)) /* Handle errors */

Then, you can set the value of your topic:

// NT4_Set<Type> takes in (<Client>, <Topic name>, <Value to set>)
NT4_SetString(client, "/SmartDashboard/Example Published Topic", "Test");

Note that just like the getter functions, you have to use the proper typed function (NT4_SetBoolean, NT4_SetNumber, NT4_SetString)

Other

Options

There are 3 different library variables you can use to modify the behaviour of the library:

• NT4_LogFile
• NT4_Port
• NT4_ErrorFunc

NT4_LogFile (default NULL) sets the file that the library will log any messages to.
NT4_Port (default 5810) sets the port to connect over.
NT4_ErrorFunc (default NULL) sets the function to call whenever an NT4 function raises an error (you can also tell this by checking NT4Error after an NT4 function call). NT4_ErrorFunc must be a function with the signature (void)(char*).

Miscellaneous functions

NT4_ClientIsConnected checks if the given client still has a valid TCP connection open:

if(!NT4_ClientIsConnected(client)) /* Handle the disconnect */

// Or:
while(NT4_ClientIsConnected(client)) {
    // Handle communications
}

NT4_GetAllTopics does as its name suggests: it gets all the topics a client is subscribed to. It fills a string array with the name of subscribed topics. It should be used alongside NT4_FreeStringArray:

char** topics;
int topicsLen;

// NT4_GetAllTopics takes in (<Client>, <Prefix>, OUT <Topics>, OUT <Topics length>)
// Out in this case means you should pass a pointer to these things. The function will set their values.
// If prefix is NULL, it gets all topics indiscriminately
if(!NT4_GetAllTopics(client, "/SmartDashboard/", &topics, &topicsLen) /* Handle errors */

// This isn't necessary; it's just an example
int i;
for(i=0;i<topicsLen;i++) {
    printf("%s\n", topics[i]);
}

// Once you're done using it, you should free topics
// NT4_FreeStringArray takes in (<String array>, <Array length>)
NT4_FreeStringArray(topics, topicsLen);

NT4_GetTopicType returns the type of the topic passed in as an NT4TypeEnum or -1 if an error occurred:

// NT4_GetTopicType takes in (<Client>, <Topic>)
NT4TypeEnum type = NT4_GetTopicType(client, "/FMSInfo/MatchType");
if(type == -1) /* Handle errors */

// This is just an example of how it may be processed
switch(type) {
    case NT4TYPE_BOOLEAN:
        // Handle this case
        break;
    // ...
}

Types and data structures

NT4Type is a struct which contains all the NT4 datatypes' hex representations for easy use. Whenever you need to pass a type to a function or perform any checks on type, you can use NT4Type.<TYPE> (eg. NT4Type.BOOLEAN).

The NT4TypeEnum enum is meant to solve the problem that in C11, there is no way to switch-case over a struct, even if all the values are known to be constant. It's essentially the same as the NT4Type struct except its fields are named NT4TYPE_<TYPE> (eg. NT4TYPE_BOOLEAN).

NT4Error is an enum that is set when calling most public NT4 functions. If the function executed successfully, it will be set to NT4ERROR_SUCCESS or 0. If logging is enabled (NT4_LogFile is not NULL), any error will be logged.

Future plans

• Support the rest of the types that can communicate over NT4 including structs
• Allow for more customization of properties and the such
• Fortify the code in this repo (especially the extremely messy JSON library)