Skip to main content

Spectranext Module

The Spectranext controller provides a memory-mapped interface for Spectrum programs to scan for WiFi networks, connect to access points, manage WiFi connectivity, and resolve hostnames. The interface is accessed via a shared memory structure mapped to a specific Spectranet page.

Memory Mapping​

The Spectranext controller registers are mapped to Spectranet page 0x48.

Accessing the Controller Registers​

To access the controller registers from a Spectrum program:

From Assembly:

.include "spectranext.inc"

; Page in Spectranext controller registers
ld a, SPECTRANEXT_CONTROLLER_PAGE  ; 0x48
call SETPAGEA                        ; Page into area A (0x1000-0x1FFF)

; Now access registers at 0x2000+
ld hl, SPECTRANEXT_BASE            ; Base address (0x2000)
ld a, SPECTRANEXT_COMMAND_SCAN_ACCESS_POINTS
ld (hl), a                          ; Write command

From C (using z88dk):

#include <spectranet.h>

// Page in Spectranext controller registers
SETPAGEA(SPECTRANEXT_CONTROLLER_PAGE);  // 0x48

// Access registers via pointer
volatile struct spectranext_controller_registers_t *ctrl = 
    (volatile struct spectranext_controller_registers_t*)0x1000;

// Wait for controller to be operational
while (ctrl->controller_status == WIFI_CONTROLLER_STATUS_OFFLINE) {
    // Small delay to avoid tight spinning
    for (volatile int i = 0; i < 1000; i++);
}

// Check if controller is being updated
if (ctrl->controller_status == WIFI_CONTROLLER_STATUS_BUSY_UPDATING) {
    // Wait for update to complete
    while (ctrl->controller_status != WIFI_CONTROLLER_STATUS_OPERATIONAL) {
        for (volatile int i = 0; i < 1000; i++);
    }
}

// Now safe to use commands
ctrl->command = SPECTRANEXT_COMMAND_SCAN_ACCESS_POINTS;

Spectranext Controller Registers Structure​

The Spectranext controller registers structure:

#pragma pack(push, 1)

struct spectranext_controller_registers_t
{
    // Offset 0x0000 (0)
    uint8_t command;                    // Command to execute (see SPECTRANEXT_COMMAND_*)
    
    // Offset 0x0001 (1)
    int8_t scan_status;                 // Scan operation status (see WIFI_SCAN_*)
    
    // Offset 0x0002 (2)
    int8_t connection_status;            // Connection status (see WIFI_CONNECT_*)
    
    // Offset 0x0003 (3)
    uint8_t scan_access_point_count;     // Number of access points found during scan
    
    // Offset 0x0004 (4)
    char access_point_name[64];          // SSID for connection command
    
    // Offset 0x0044 (68)
    char access_point_password[64];      // Password for connection command
    
    // Offset 0x0084 (132)
    uint8_t controller_status;           // Controller status (see WIFI_CONTROLLER_STATUS_*)
    
    // Offset 0x0085 (133)
    int8_t gethostbyname_status;         // gethostbyname operation status (see GETHOSTBYNAME_STATUS_*)
    
    // Offset 0x0086 (134)
    uint32_t gethostbyname_ipv4_result;  // IPv4 address result (network byte order, big-endian)
    
    // Offset 0x008A (138)
    char gethostbyname_hostname[96];     // Hostname input for gethostbyname query
    
    // Offset 0x00EA (234)
    char reserved[22];                   // Reserved for future use
    
    // Offset 0x0100 (256)
    struct
    {
        char name[64];                   // Access point SSID
    } access_points[32];                 // Array of found access points (max 32)
};

#pragma pack(pop)

Command Constants​

Spectranext Commands​

Commands are written to command field:

  • SPECTRANEXT_COMMAND_SCAN_ACCESS_POINTS (1) - Scan for available WiFi access points
  • SPECTRANEXT_COMMAND_CONNECT_ACCESS_POINT (2) - Connect to the access point specified in access_point_name and access_point_password
  • SPECTRANEXT_COMMAND_DISCONNECT (3) - Disconnect from the currently connected access point
  • SPECTRANEXT_COMMAND_GETHOSTBYNAME (4) - Resolve hostname to IPv4 address (see Hostname Resolution section)

Scan Status​

The scan_status field indicates the current scan operation state:

  • WIFI_SCAN_NONE (0) - No scan operation in progress
  • WIFI_SCAN_SCANNING (1) - Scan operation in progress
  • WIFI_SCAN_COMPLETE (2) - Scan completed successfully
  • WIFI_SCAN_FAILURE (-1) - Scan operation failed

Connection Status​

The connection_status field indicates the current WiFi connection state:

  • WIFI_CONNECT_DISCONNECTED (0) - Not connected
  • WIFI_CONNECT_CONNECTING (1) - Connection attempt in progress
  • WIFI_CONNECT_CONNECT_SUCCESS (2) - Connected successfully
  • WIFI_CONNECT_CONNECT_IP_OBTAINED (3) - Connected and IP address obtained
  • WIFI_CONNECT_CONNECT_FAILURE (-1) - Connection failed

Controller Status​

The controller_status field indicates the overall state of the Spectranext controller hardware:

  • WIFI_CONTROLLER_STATUS_OFFLINE (0) - Controller is offline or initializing
  • WIFI_CONTROLLER_STATUS_BUSY_UPDATING (1) - WiFi controller firmware is being updated
  • WIFI_CONTROLLER_STATUS_OPERATIONAL (2) - Controller is operational and ready for use

Important: Before using any commands, check that controller_status is WIFI_CONTROLLER_STATUS_OPERATIONAL. If the status is WIFI_CONTROLLER_STATUS_BUSY_UPDATING, the system is updating the WiFi firmware and will reboot when complete. During this time, operations should not be attempted.

Hostname Resolution Status​

The gethostbyname_status field indicates the result of a hostname resolution operation:

  • GETHOSTBYNAME_STATUS_NONE (0) - No operation in progress or operation not started
  • GETHOSTBYNAME_STATUS_SUCCESS (1) - Hostname resolved successfully, result in gethostbyname_ipv4_result
  • GETHOSTBYNAME_STATUS_HOST_NOT_FOUND (-1) - Hostname not found
  • GETHOSTBYNAME_STATUS_TIMEOUT (-2) - Resolution timed out
  • GETHOSTBYNAME_STATUS_SYSTEM_FAILURE (-3) - System error during resolution

Implementation Details​

Page Mapping​

The Spectranext controller registers are mapped to page 0x48 (SPECTRANEXT_CONTROLLER_PAGE). When this page is mapped into area A (0x1000-0x1FFF), the structure is accessible starting at address 0x1000 (SPECTRANEXT_BASE).

Communication Protocol​

  1. Check Controller Status: Before using any commands, verify that controller_status is WIFI_CONTROLLER_STATUS_OPERATIONAL
  2. Write Command: Write a command value to command field (offset 0x0000)
  3. Poll Status: Read appropriate status fields (scan_status, connection_status, or gethostbyname_status) to check operation progress
  4. Read Results: Read results from appropriate fields (scan_access_point_count, access_points[], gethostbyname_ipv4_result, etc.)

Hostname Resolution​

NOTE: These operations are not required and only explain how spectranext does name resolution under the hood of GETHOSTBYNAME API Call.

To (manually) resolve a hostname to an IPv4 address:

  1. Check Controller Status: Ensure controller_status is WIFI_CONTROLLER_STATUS_OPERATIONAL
  2. Copy Hostname: Copy the null-terminated hostname string to gethostbyname_hostname (max 95 characters)
  3. Reset Status: Set gethostbyname_status to GETHOSTBYNAME_STATUS_NONE (0)
  4. Issue Command: Write SPECTRANEXT_COMMAND_GETHOSTBYNAME to command
  5. Wait for Completion: Poll gethostbyname_status until it becomes non-zero
  6. Check Result:
    • If GETHOSTBYNAME_STATUS_SUCCESS, read IPv4 address from gethostbyname_ipv4_result (network byte order, big-endian)
    • Otherwise, handle the error according to the status code

Controller Status Lifecycle​

The Spectranext controller status follows this lifecycle:

  • Initialization: On system startup, controller_status starts as WIFI_CONTROLLER_STATUS_OFFLINE
  • Version Check: The system checks if the Wi-Fi firmware needs updating
  • If Update Needed: Status changes to WIFI_CONTROLLER_STATUS_BUSY_UPDATING during firmware update
  • After Update: Status changes to WIFI_CONTROLLER_STATUS_OPERATIONAL and the system reboots
  • If No Update: Status changes directly to WIFI_CONTROLLER_STATUS_OPERATIONAL

Programs should wait for controller_status to become WIFI_CONTROLLER_STATUS_OPERATIONAL before attempting any operations.