Skip to main content

WiFi Module

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

Memory Mapping​

The WiFi configuration registers are mapped to Spectranet page 0x48.

Accessing the WiFi Registers​

To access the WiFi registers from a Spectrum program:

From Assembly:

.include "spectranet.inc"

; Page in WiFi configuration registers
ld a, WIFI_CONFIG_SPECTRANET_PAGE  ; 0x48
call SETPAGEA                        ; Page into area A (0x1000-0x1FFF)

; Now access registers at 0x1000+
ld hl, 0x1000                       ; Base address of WiFi registers
ld a, WIFI_COMMAND_SCAN_ACCESS_POINTS
ld (hl), a                          ; Write command

From C (using z88dk):

#include <spectranet.h>

// Page in WiFi configuration registers
SETPAGEA(WIFI_CONFIG_SPECTRANET_PAGE);

// Access registers via pointer
volatile struct wifi_config_registers_t *wifi = (volatile struct wifi_config_registers_t*)0x1000;

// Wait for WiFi controller to be operational
while (wifi->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 (wifi->controller_status == WIFI_CONTROLLER_STATUS_BUSY_UPDATING) {
    // Wait for update to complete
    while (wifi->controller_status != WIFI_CONTROLLER_STATUS_OPERATIONAL) {
        for (volatile int i = 0; i < 1000; i++);
    }
}

// Now safe to use WiFi commands
wifi->command = WIFI_COMMAND_SCAN_ACCESS_POINTS;

WiFi Configuration Registers Structure​

The WiFi configuration registers structure:

#pragma pack(push, 1)

struct wifi_config_registers_t
{
    // Offset 0x0000 (0)
    uint8_t command;                    // Command to execute (see WIFI_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;           // WiFi controller status (see WIFI_CONTROLLER_STATUS_*)
    
    // Offset 0x0085 (133)
    char reserved[123];                  // 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​

WiFi Commands​

Commands are written to command field:

  • WIFI_COMMAND_SCAN_ACCESS_POINTS (1) - Scan for available WiFi access points
  • WIFI_COMMAND_CONNECT_ACCESS_POINT (2) - Connect to the access point specified in access_point_name and access_point_password
  • WIFI_COMMAND_DISCONNECT (3) - Disconnect from the currently connected access point

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 WiFi controller hardware:

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

Important: Before using WiFi 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, WiFi operations should not be attempted.

Implementation Details​

Page Mapping​

The WiFi configuration registers are mapped to page 0x48 (WIFI_CONFIG_SPECTRANET_PAGE). When this page is mapped into area A (0x1000-0x1FFF), the structure is accessible starting at address 0x1000.

Communication Protocol​

  1. Check Controller Status: Before using WiFi 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 scan_status or connection_status to check operation progress
  4. Read Results: Read results from appropriate fields (scan_access_point_count, access_points[], etc.)

Controller Status Lifecycle​

The WiFi controller status follows this lifecycle:

  • Initialization: On system startup, controller_status starts as WIFI_CONTROLLER_STATUS_OFFLINE
  • Version Check: The system checks if the WiFi 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 WiFi operations.

String Handling​

  • SSID and password strings are null-terminated C strings
  • Maximum length is 63 characters (plus null terminator) for 64-byte fields