search

remy / next-http

Send and recieve http requests into banks - for the Spectrum Next
44 stars 6 forks source link
cspect dot-command esp nextbasic spectrum-next zxnext zxnextos

readme

http - for the Spectrum Next

A utility for application developers to talk to web servers to exchange blocks of data, such as high scores, game progress. The .http dot command can also download and save to files over the web.

Usage

; Send 1024 bytes from bank 22 to http://192.168.1.100:8080/send
.http post -b 22 -l 1024 -h 192.168.1.100 -p 8080 -u /send

; Download and save Manic Miner http://zxdb.remysharp.com/get/18840
.http -h zxdb.remysharp.com -u /get/18840 -f manic.tap

; Load http://data.remysharp.com/18 (the text "hello world") into bank 20 and flash border red (2)
.http get -b 20 -h data.remysharp.com -u /18 -v 2

Options:

Note that by default a GET request will empty out the bank selected. If you want to preserve the data in the bank, use a negative value for the offset, i.e. -b 5 -o -0 will load the http request into bank 5, preserving the RAM and inserting at memory position 0 (in fact, $4000 in RAM).

Run with no arguments to see the help.

*Cpsect's emulated ESP support used 7-bit, which means if you want to send binary data, you will need to base64 encode your payload. Using the -7 flag with http will support decoding and support Cpsect. This is not required if you only plan to exchange 7-bit data (like readable text) or support hardware. See the example folder for a server returning binary using base64 encoding.

Using from NextBASIC

If the dot command isn't (currently) shipped as part of the distro and you want to ship http as part of your project, you will need to call the dot command from a relative path. You might also need to set variables, such as a bank number through NextBASIC and pass this to http. At time of writing (Feb 2021) the .$ command doesn't support relative paths, so NextBASIC variable reading is support as part of http.

The only variables that http supports are single letter string variables.

Assuming http is in the same directory as your NextBASIC file, the following prefix is required: ../ (dot dots and a slash). See the code below for the full example:

10 BANK NEW b
20 b$ = STR$ b : REM store as a string
30 c$ = "256" : REM we'll send 256 bytes from bank $b
30 ../http post -b b$ -h example.com -l c$
40 PRINT "done"

Note that http will expect a BASIC variable to represent a single argument value and you cannot combine multiple arguments into a single variable (i.e. h$="-h example -p 8080 won't work).

Rolling banks

For file saving, rolling banks are used by default. What this means is that the http request is buffered into memory for as many memory banks are available (16K banks - two 8K pages). Before the file is fully downloaded a size check is run against the content-length and your available memory, and if there's not enough, .http will exit with error M Not enough memory.

Rolling banks is used to provide as much support across different SD card speeds. If you need to download more than your memory limits and you have a fast SD card (class 10 is a good default), then you can disable rolling banks using the -r switch as an argument.

Installation

You can save the http to your own /dot directory, or you can run it from your working directory using a relative path ../http.

Download the latest release here

Example servers

I've written a number of example servers in different languages for you to try out.

Limits

Not supported / potential future

Error codes

Testing

Assuming that http is in your /dot/ directory, there are two verification programs in the example folder. Download verify.bas and run it and if it succeeds you'll see the following screen:

If any of the sections fail however, there is a debug script available in capture-esp.bas which uses http-debug.dot in the same directory as capture-esp.bas.

The capture-esp.bas will test a simple 4K file and generate 4k-esp-bank.bin in the same working directory which contains full debug exchange between your machine and the ESP chip uses to send data. If you share that file with me either via issues or via email I can use it to debug.

Debugging and problems

This repo also includes a debug build of http. The difference is that it will add all the ESP read and write to the second half of the bank you use. This way you can debug from the real hardware and capture exactly what's going on.

Important the debug dot command uses the second half of the bank you use, so ideally test with less than 8K to help debugging.

If you need to file an issue, this information is extremely valuable for debugging - and if you're not comfortable including the file in an issue as an attachment, you can email me directly at remy@remysharp.com. To capture this, run:

10 ../http-debug.dot -h example.com -u / -b 20
20 SAVE "http-debug.bin" BANK 20

Then include the http-debug.bin that was saved on your Next to help debug the issue.

Notes on http-debug.dot

  1. Does not erase the bank
  2. The contents of the State structure (in state.asm) are written to the 2nd half of the bank, i.e. the second 8K page
  3. After the State object, around 519 bytes later, the ESP exchange are stored, including the AT commands and ESP raw response.
  4. Wifi.getPacket writes to the end of the bank with the IX register state as a stack like array - this is to debug the final parsing of the base64 encoded packet

With special thanks to

Development

License for .HTTP

It's in the license link, but all the same:

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND

This software simplifies access to the web from a machine that is typically disconnected. Please use this software for good, but I provide no warranty, or help for that matter, if this software is used for bad. It is what it is.