Skip to content

Firmware Update

Document Context

  • Purpose: Guides through remote firmware update procedures for whatwatt Go device via HTTP upload interface
  • When to use: When planning or executing firmware upgrades without physical device access
  • Prerequisites: Administrative access rights, firmware binary file from whatwatt support
  • Related to: Factory reset procedures, system information endpoints, device restart methods
  • Validates against: Real firmware upgrade sequences with update verification steps

Key Facts

  • Endpoint: /load (HTTP POST for firmware upload)
  • Methods: POST (multipart/form-data), GET (update status)
  • Authentication: Admin credentials required for firmware modifications
  • Response format: JSON status with progress indicators and error messages
  • Error codes: File validation errors, insufficient storage, update failure states

Authentication

When a Web UI password is set, HTTP endpoints require HTTP authentication.

Firmware 1.10.X and later: Uses HTTP Digest authentication - Server challenges with WWW-Authenticate: Digest … (realm is the device hostname) - Algorithm: MD5-sess (device advertises MD5-sess; integrity variant supported) - qop: auth (and optionally auth-int for requests with body integrity) - Nonce and opaque are issued by the device; the client must include cnonce and increment nc - Expired nonce: server may return 401 with WWW-Authenticate: …, stale=true. In that case, retry the same request once using the new server challenge, a new cnonce, and reset nc=00000001.

Firmware before 1.10.X: Uses HTTP Basic authentication - Server challenges with WWW-Authenticate: Basic realm="..." - Credentials are base64-encoded in Authorization: Basic <encoded-credentials>

Recommended approach: Use --anyauth in curl to automatically detect and use the appropriate method:

curl --anyauth -u ":<password>" http://whatwatt-ABCDEF.local/api/v1/system

Alternative Method

Firmware updates can also be performed from the WebUI of the device for easier manual updates.

Endpoint Details

This endpoint allows you to update the device firmware. The firmware file should be sent in multipart/form-data format.

Parameter Value
Endpoint /load
Method POST
Content Type multipart/form-data
Response Content Type text/plain

Update Process

Request Format

The firmware file must be uploaded using the multipart/form-data format with the field name file.

Example

curl -i -F file=@upgrade_file.bin http://192.168.1.100/load

Parameters

  • -F file=@upgrade_file.bin: Uploads the file upgrade_file.bin from the current directory
  • -i: Include response headers in output
  • Replace 192.168.1.100 with your device's IP address
  • Replace upgrade_file.bin with the actual firmware file name

Response

The server will respond with status information about the upload and update process.

Reboot after successful update

After the firmware is uploaded and verified, the device automatically reboots to apply the new version. This is the only routine scenario that requires a reboot. See Device Restart for reboot behavior and expected downtime.

Important Considerations

Firmware Update Safety

  • Ensure the firmware file is specifically designed for your device model
  • Do not interrupt the update process once started
  • The device will reboot automatically after a successful update (routine and expected)
  • Keep the device powered during the entire update process

File Format Requirements

  • Firmware files typically have .bin extension
  • Only use firmware files provided by the device manufacturer
  • Verify file integrity before upload if checksums are provided

Multipart/Form-Data Background

multipart/form-data is a media type used to encode files and other form data when uploading via HTTP POST requests. This format:

  • Splits form data into multiple parts separated by boundaries
  • Encodes each part with its own content type and disposition metadata
  • Enables robust handling of binary data and complex file uploads
  • Was standardized in RFC 2388 (1998) to overcome limitations of application/x-www-form-urlencoded

This format allows each part of the form to be processed independently, making it ideal for file uploads like firmware updates.

Troubleshooting

Common Issues

Issue Solution
File not found Check the file path and ensure the firmware file exists
Permission denied Verify you have read access to the firmware file
Connection timeout Check network connectivity to the device
Invalid firmware Ensure the firmware is compatible with your device model

Example Error Responses

# File too large
HTTP/1.1 413 Payload Too Large

# Invalid file format
HTTP/1.1 400 Bad Request

# Device busy
HTTP/1.1 503 Service Unavailable

Best Practices

  1. Backup Settings: Save current device configuration before updating
  2. Stable Power: Ensure reliable power supply during update
  3. Verify Version: Check current firmware version before and after update
  4. Test Functionality: Verify device operation after successful update