FdToNBString

File Descriptor to NBString Example

Overview

This NetBurner application demonstrates how to capture file descriptor I/O data to an NBString object instead of using the file descriptor as originally intended by a library. This technique is useful for logging, debugging, or printing data to serial output.

The example utilizes the NBStringBuilder class which associates a buffer with a file descriptor that can then be used with API's that utilize file descriptors. The NBStringBuilder class is defined in nbstring.h. The NBStringBuilder class supports the use of file descriptor functions defined in iosys.h such as: read(), write(), and close().

Purpose

Many NetBurner libraries utilize file descriptors (fd) for data input/output transmission, including:

• TCP
• WebSockets
• HTTP
• FTP
• Serial communication
• Configuration system

This example shows how to redirect file descriptor data to a local NBString variable for further processing.

Key Components

NBStringBuilder Class

• Associates a buffer with a file descriptor
• Defined in nbstring.h
• Supports standard file descriptor functions from iosys.h (read, write, close)
• Enables capturing fd data to NBString objects

System Diagnostics Integration

• Uses EnableSystemDiagnostics() to maintain a diagnostics data set as JSON
• Demonstrates writing diagnostics data to an NBString instead of TCP socket or serial
• Default diagnostics data set is approximately 2.6KB but can grow based on:
  • Number of tasks
  • Socket usage
  • User-defined variables in diagnostic set

Application Flow

1. Initialization
   • Network stack initialization
   • Enable system diagnostics
   • Start HTTP server on port 80
   • Wait for active network connection
2. User Interaction
   • Prompts user to press any key to print system diagnostics
   • Waits for user input via getchar()
3. Data Capture Process
   • Reserves 8KB buffer space (overkill for default diagnostics but safe)
   • Allocates file descriptor from fd pool
   • Writes system diagnostics data to NBStringBuilder object
   • Moves data from NBStringBuilder to NBString variable
   • Closes the allocated file descriptor
4. Output
   • Prints captured diagnostics data to serial output
   • Data is now available for other uses (storage, transmission, etc.)

Memory Considerations

• Buffer Size: 8192 bytes (8KB) reserved for diagnostics data
• Default Size: ~2.6KB for basic diagnostics
• Growth Factors: Additional tasks, sockets, and user variables increase size

Potential Use Cases

Once captured in an NBString, the diagnostics data can be:

• Stored to persistent storage (flash memory, SD card)
• Transmitted remotely (email, syslog, FTP)
• Logged for debugging purposes
• Processed or filtered before use

Key APIs Used

• EnableSystemDiagnostics() - Enables system diagnostic data collection
• NBStringBuilder::reservespace() - Allocates buffer space
• NBStringBuilder::GetActiveFD() - Gets file descriptor for the builder
• pDiagServer() - Writes diagnostics data to specified file descriptor
• NBStringBuilder::moveTo() - Transfers data to NBString object
• close() - Closes file descriptor

Network Features

• HTTP server enabled on default port 80
• Waits up to 5 seconds for active network connection
• Network stack fully initialized before main loop

Usage

1. Build and deploy the application to NetBurner hardware
2. Connect to the device via serial terminal
3. Press any key when prompted to capture and display system diagnostics
4. The diagnostics JSON data will be printed to the serial output