NB Approve Shutdown

NBApproveShutdown Application

Overview

The NBApproveShutdown application demonstrates how to implement safe system shutdown handling for NetBurner embedded systems. This application provides a callback mechanism that allows developers to put their system in a safe state before application updates, configuration updates, or custom reboot events occur.

Purpose

The primary purpose of this application is to showcase the NBApproveShutdown() callback function, which enables applications to:

• Close active TCP sockets before shutdown
• Ensure Flash and file system write operations are complete
• Put critical peripherals in a safe state
• Control whether a shutdown request should be approved or denied

System Requirements

• NetBurner Hardware
• NetBurner Network Development Kit (NNDK)
• Serial terminal for interaction

Application Features

Shutdown Callback Function

The application implements a custom NBApproveShutdown() function that overrides the default system implementation. This function handles different shutdown reasons:

• Code Update (SHUTDOWN_CODEUPDATE): Triggered when a firmware update is requested
• Configuration Reboot (SHUTDOWN_CONFIGURE_REBOOT): Triggered when configuration changes require a reboot
• Custom Reboot (SHUTDOWN_CUSTOM_REBOOT): Application-defined reboot scenarios

Custom Reboot Reason

Custom reboot reason. System reasons start at 1, so pick something much larger

#define SHUTDOWN_CUSTOM_REBOOT 100
 
if( NBApproveShutdown(SHUTDOWN_CUSTOM_REBOOT))
{
     OSTimeDly(TICKS_PER_SECOND * 5);
     ForceReboot();
}

Interactive Serial Menu

The application provides a simple serial port menu interface with the following options:

1. Enable Shutdown - Allows shutdown requests to proceed
2. Disable Shutdown - Blocks shutdown requests for testing
3. Custom Reboot Request - Initiates a custom reboot sequence

Web Server Integration

The application includes a basic web server that starts on port 80, allowing for potential web-based interactions and monitoring.

How It Works

Shutdown Approval Process

1. When a shutdown event occurs, the system calls NBApproveShutdown() with a reason code
2. The application can examine the reason and current system state
3. Based on application logic, the function returns:
   • true to approve the shutdown
   • false to abort the shutdown

Global Control Flag

The application uses a global boolean flag bAllowShutdown to demonstrate shutdown control:

• When true: All shutdown requests are approved
• When false: All shutdown requests are denied (except unknown reasons)

Usage Instructions

Building and Running

1. Compile the application using the NetBurner development tools
2. Flash the application to your NetBurner device
3. Connect a serial terminal to the device
4. Monitor the serial output for menu options and status messages

Testing Shutdown Behavior

1. Enable/Disable Testing: Use menu options 1 and 2 to toggle shutdown approval
2. Custom Reboot Testing: Use menu option 3 to trigger a custom reboot sequence
3. Update Testing: Attempt a firmware update to test the code update shutdown path

Serial Commands

• Press 1 to enable shutdown approval
• Press 2 to disable shutdown approval
  
• Press 3 to request a custom reboot
• Press any other key to display the menu

Code Structure

Key Components

• NBApproveShutdown(): Main callback function that processes shutdown requests
• displayMenu(): Shows available menu options and current status
• processCommand(): Handles serial input and executes commands
• UserMain(): Application entry point and main loop

Important Constants

#define SHUTDOWN_CODEUPDATE         (1)   // Code update requested
#define SHUTDOWN_CONFIGURE_REBOOT   (2)   // Configuration reboot requested
#define SHUTDOWN_CUSTOM_REBOOT    (100)   // Custom application reboot

Implementation Notes

Safety Considerations

• The callback function includes a 1-second delay to ensure serial output completes before reboot
• Unknown shutdown reasons are automatically rejected for safety
• The weak reference mechanism allows easy override of default system behavior

Customization Points

Developers can customize this application by:

• Adding specific hardware shutdown sequences in the callback function
• Implementing additional shutdown reason codes
• Adding more sophisticated approval logic based on system state
• Integrating with web-based monitoring and control

Example Output

Web Application: NB Approve Shutdown
NNDK Revision: [Version Number]
 
----- Main Menu -----
1 - Enable  Shutdown
2 - Disable Shutdown
3 - Custom Reboot Request
Current bAllowShutdown = true

Development Guidelines

Best Practices

1. Always include appropriate delays before reboot to ensure data integrity
2. Test both approved and denied shutdown scenarios
3. Handle all known shutdown reasons explicitly
4. Consider system state when making approval decisions
5. Log shutdown events for debugging and monitoring

Integration Tips

• Use this pattern in production applications to ensure graceful shutdowns
• Combine with watchdog timers for additional safety
• Consider network notification of shutdown events
• Implement persistent logging of shutdown requests and approvals