HTTP and HTTPS example application for Mbed OS 5

Dependencies:   mbed-http

This application demonstrates how to make HTTP and HTTPS requests and parse the response from Mbed OS 5.

It consists of six example applications, which you can select in source/select-demo.h:

Response parsing is done through nodejs/http-parser.

Note: HTTPS requests do not work on targets with less than 128K of RAM due to the size of the TLS handshake. For more background see mbed-http.

To build

  1. If you're using WiFi, specify the credentials in mbed_app.json.
  2. Build the project in the online compiler or using Mbed CLI.
  3. Flash the project to your development board.
  4. Attach a serial monitor to your board to see the debug messages.

Defining the network interface

This application uses the on-board network interface for your board. If you use an external network interface (f.e. a WiFi module) you need to add the driver to this project. Then, open network-helper.h and specify which network driver to use.

More information is in the Mbed OS documentation under IP Networking.

Entropy (or lack thereof)

On all platforms that do not have the TRNG feature, the application is compiled without TLS entropy sources. This means that your code is inherently unsafe and should not be deployed to any production systems. To enable entropy, remove the MBEDTLS_NO_DEFAULT_ENTROPY_SOURCES and MBEDTLS_TEST_NULL_ENTROPY macros from mbed_app.json.

Flash size

Default flash size for HTTPS is very large, as the application is loading the default Mbed TLS configuration. To use a more optimized version, you can disable unused cypher suites and other Mbed TLS features with a custom configuration file. Create a new configuration file, then add in mbed_app.json:

"MBEDTLS_CONFIG_FILE=\"mbedtls_config.h\""

to the macros array.

Running tests

You can run the integration tests from this project via Mbed CLI.

  1. In select-demo.h set the DEMO macro to DEMO_TESTS.
  2. Set your WiFi credentials in mbed_app.json.
  3. Then run the tests via:

$ mbed test -v -n mbed-http-tests-tests-*

Tested on

  • K64F with Ethernet.
  • NUCLEO_F411RE with ESP8266.
  • ODIN-W2 with WiFi.
  • K64F with Atmel 6LoWPAN shield.
  • DISCO-L475VG-IOT01A with WiFi (requires the wifi-ism43362 driver).
  • Mbed Simulator.
Committer:
Jan Jongboom
Date:
Fri Jan 04 13:32:26 2019 +0100
Revision:
35:4b847971db1b
Parent:
33:2efadc4d8784
Update to Mbed OS 5.11

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Jan Jongboom 30:4825e4f38844 1 # HTTP/HTTPS example for Mbed OS 5
Jan Jongboom 0:85fdc69bc10c 2
Jan Jongboom 30:4825e4f38844 3 This application demonstrates how to make HTTP and HTTPS requests and parse the response from Mbed OS 5.
Jan Jongboom 0:85fdc69bc10c 4
Jan Jongboom 26:22f87edb433c 5 It consists of six demo's, which you can select in ``source/select-demo.h``.
Jan Jongboom 0:85fdc69bc10c 6
Jan Jongboom 11:72c089200302 7 * HTTP demo:
Jan Jongboom 4:27fd8efb5bab 8 * Does a GET request to http://httpbin.org/status/418.
Jan Jongboom 4:27fd8efb5bab 9 * Does a POST request to http://httpbin.org/post.
Jan Jongboom 11:72c089200302 10 * HTTPS demo:
Jan Jongboom 30:4825e4f38844 11 * Does a GET request to https://os.mbed.com/media/uploads/mbed_official/hello.txt.
Jan Jongboom 4:27fd8efb5bab 12 * Does a POST request to https://httpbin.org/post.
Jan Jongboom 11:72c089200302 13 * HTTP demo with socket re-use.
Jan Jongboom 11:72c089200302 14 * HTTPS demo with socket re-use.
Jan Jongboom 25:a8be9f3a530c 15 * HTTP demo over IPv6.
Jan Jongboom 25:a8be9f3a530c 16 * HTTPS demo with chunked requests.
Jan Jongboom 0:85fdc69bc10c 17
Jan Jongboom 0:85fdc69bc10c 18 Response parsing is done through [nodejs/http-parser](https://github.com/nodejs/http-parser).
Jan Jongboom 0:85fdc69bc10c 19
Jan Jongboom 17:97b1dd566b07 20 **Note:** HTTPS requests do not work on targets with less than 128K of RAM due to the size of the TLS handshake. For more background see [mbed-http](https://developer.mbed.org/teams/sandbox/code/mbed-http).
Jan Jongboom 17:97b1dd566b07 21
Jan Jongboom 0:85fdc69bc10c 22 ## To build
Jan Jongboom 0:85fdc69bc10c 23
Jan Jongboom 30:4825e4f38844 24 1. If you're using WiFi, specify the credentials in `mbed_app.json`.
Jan Jongboom 30:4825e4f38844 25 1. Build the project in the online compiler or using Mbed CLI.
Jan Jongboom 30:4825e4f38844 26 1. Flash the project to your development board.
Jan Jongboom 30:4825e4f38844 27 1. Attach a serial monitor to your board to see the debug messages.
Jan Jongboom 30:4825e4f38844 28
Jan Jongboom 30:4825e4f38844 29 ## Defining the network interface
Jan Jongboom 30:4825e4f38844 30
Jan Jongboom 30:4825e4f38844 31 This application uses the on-board network interface for your board. If you use an external network interface (f.e. a WiFi module) you need to add the driver to this project. Then, open `network-helper.h` and specify which network driver to use.
Jan Jongboom 30:4825e4f38844 32
Jan Jongboom 30:4825e4f38844 33 More information is in the Mbed OS documentation under [IP Networking](https://os.mbed.com/docs/latest/reference/ip-networking.html).
Jan Jongboom 0:85fdc69bc10c 34
Jan Jongboom 0:85fdc69bc10c 35 ## Entropy (or lack thereof)
Jan Jongboom 0:85fdc69bc10c 36
Jan Jongboom 30:4825e4f38844 37 On all platforms that do not have the `TRNG` feature, the application is compiled without TLS entropy sources. This means that your code is inherently unsafe and should not be deployed to any production systems. To enable entropy, remove the `MBEDTLS_NO_DEFAULT_ENTROPY_SOURCES` and `MBEDTLS_TEST_NULL_ENTROPY` macros from mbed_app.json.
Jan Jongboom 0:85fdc69bc10c 38
Jan Jongboom 19:fbf5b033149a 39 ## Flash size
Jan Jongboom 19:fbf5b033149a 40
Jan Jongboom 30:4825e4f38844 41 Default flash size for HTTPS is very large, as the application is loading the default Mbed TLS configuration. To use a more optimized version, you can disable unused cypher suites and other Mbed TLS features with a custom configuration file. Create a new configuration file, then add in `mbed_app.json`:
Jan Jongboom 19:fbf5b033149a 42
Jan Jongboom 19:fbf5b033149a 43 ```
Jan Jongboom 23:6a9d776c9794 44 "MBEDTLS_CONFIG_FILE=\"mbedtls_config.h\""
Jan Jongboom 19:fbf5b033149a 45 ```
Jan Jongboom 19:fbf5b033149a 46
Jan Jongboom 19:fbf5b033149a 47 to the `macros` array.
Jan Jongboom 19:fbf5b033149a 48
Jan Jongboom 35:4b847971db1b 49 ## Running tests
Jan Jongboom 35:4b847971db1b 50
Jan Jongboom 35:4b847971db1b 51 You can run the integration tests from this project via Mbed CLI.
Jan Jongboom 35:4b847971db1b 52
Jan Jongboom 35:4b847971db1b 53 1. In `select-demo.h` set the `DEMO` macro to `DEMO_TESTS`.
Jan Jongboom 35:4b847971db1b 54 1. Set your WiFi credentials in `mbed_app.json`.
Jan Jongboom 35:4b847971db1b 55 1. Then run the tests via:
Jan Jongboom 35:4b847971db1b 56
Jan Jongboom 35:4b847971db1b 57 ```
Jan Jongboom 35:4b847971db1b 58 $ mbed test -v -n mbed-http-tests-tests-*
Jan Jongboom 35:4b847971db1b 59 ```
Jan Jongboom 35:4b847971db1b 60
Jan Jongboom 0:85fdc69bc10c 61 ## Tested on
Jan Jongboom 0:85fdc69bc10c 62
Jan Jongboom 0:85fdc69bc10c 63 * K64F with Ethernet.
Jan Jongboom 0:85fdc69bc10c 64 * NUCLEO_F411RE with ESP8266.
Jan Jongboom 17:97b1dd566b07 65 * ODIN-W2 with WiFi.
Jan Jongboom 25:a8be9f3a530c 66 * K64F with Atmel 6LoWPAN shield.
Jan Jongboom 35:4b847971db1b 67 * DISCO-L475VG-IOT01A with WiFi (requires the [wifi-ism43362](https://github.com/ARMmbed/wifi-ism43362/) driver).
Jan Jongboom 33:2efadc4d8784 68 * [Mbed Simulator](https://github.com/janjongboom/mbed-simulator).