diff --git a/Documentation/applications/system/curl/index.rst b/Documentation/applications/system/curl/index.rst new file mode 100644 index 00000000000..043f47dafc1 --- /dev/null +++ b/Documentation/applications/system/curl/index.rst @@ -0,0 +1,107 @@ +=============================== +``curl`` HTTP client command +=============================== + +The ``curl`` command is a small command-line HTTP client built on top of the +``netutils`` webclient library. It mimics a subset of the well known +`curl `_ tool so the same option syntax can +be used to exercise HTTP servers from the NuttShell (NSH). + +It is **HTTP only** (no HTTPS/TLS) and supports the following options: + +============ ================================================================ +Option Description +============ ================================================================ +``-X`` HTTP method (default ``GET``, or ``POST`` when a body is sent). +``-H`` Add a request header (e.g. ``-H Content-Type:application/json``). +``-d`` Raw request body; ``-d @file`` reads the body from a file. +``-F`` multipart/form-data field; ``-F name=@file`` uploads a file. +``-o`` Write the response body to a file instead of stdout. +``-v`` Verbose: print the request line and status. +============ ================================================================ + +Configuration +============= + +- ``CONFIG_SYSTEM_CURL``: Enable the ``curl`` command. +- ``CONFIG_NETUTILS_WEBCLIENT``: HTTP client library (required dependency). +- ``CONFIG_NET_TCP``: TCP support (required by the webclient). + +The following additional options are available: + +- ``CONFIG_SYSTEM_CURL_PROGNAME`` - Program name (default: ``curl``). +- ``CONFIG_SYSTEM_CURL_PRIORITY`` - Task priority (default: 100). +- ``CONFIG_SYSTEM_CURL_STACKSIZE`` - Task stack size. A networked HTTP + client needs a comfortable stack; 8192 is a safe value. +- ``CONFIG_SYSTEM_CURL_BUFFERSIZE`` - Transfer buffer size (default: 512). + It must be large enough to hold the whole request/response header line. + +Usage +===== + +.. code-block:: text + + curl [options] ... + +Examples +======== + +Download a file and save it with ``-o`` (using the public ``httpbin.org`` +HTTP test service): + +.. code-block:: text + + nsh> curl -o /mnt/dl.json http://httpbin.org/json + curl: HTTP 200 + nsh> curl -o /mnt/img.png http://httpbin.org/image/png + curl: HTTP 200 + nsh> ls -l /mnt/img.png + -rw-rw-rw- 8090 /mnt/img.png + +Send a JSON body with POST (``-d`` selects ``POST`` automatically, ``-H`` sets +the content type). ``httpbin.org/post`` echoes back what it received: + +.. code-block:: text + + nsh> curl -H Content-Type:application/json -d '{"temp":25.3,"hum":60}' http://httpbin.org/post + { + "data": "{\"temp\":25.3,\"hum\":60}", + "headers": { + "Content-Type": "application/json", + "Host": "httpbin.org" + }, + "json": { + "hum": 60, + "temp": 25.3 + }, + "url": "http://httpbin.org/post" + } + curl: HTTP 200 + +Select a different method with ``-X``: + +.. code-block:: text + + nsh> curl -X PUT -d '{"x":1}' http://httpbin.org/put + curl: HTTP 200 + +Upload a file with multipart/form-data (``-F name=@file``) and download it +back with ``-o``: + +.. code-block:: text + + nsh> curl -F file=@/mnt/nuttx_logo.png "http://192.168.1.10:8000/upload?version=logo1" + {"filename":"nuttx_logo.png","sha256":"ca278dcb...","size_bytes":40343}curl: HTTP 201 + nsh> curl -o /mnt/logo_back.png http://192.168.1.10:8000/download/logo1/nuttx_logo.png + curl: HTTP 200 + +.. note:: + + The webclient transfer buffer is small and the request has a short timeout, + so prefer small files (a few KB up to ~100 KB). HTTPS is not supported; use + plain ``http://`` URLs only. + +See Also +======== + +- `curl manual page `_ diff --git a/Documentation/platforms/arm/stm32h7/boards/linum-stm32h753bi/index.rst b/Documentation/platforms/arm/stm32h7/boards/linum-stm32h753bi/index.rst index fab58dab4ba..3e2c85d0d9c 100644 --- a/Documentation/platforms/arm/stm32h7/boards/linum-stm32h753bi/index.rst +++ b/Documentation/platforms/arm/stm32h7/boards/linum-stm32h753bi/index.rst @@ -802,6 +802,92 @@ This configuration is focused on network testing using the ethernet periferal:: 10 packets transmitted, 10 received, 0% packet loss, time 10100 ms rtt min/avg/max/mdev = 0.000/1.000/10.000/3.000 ms +curl +---- + +Based on the ``netnsh`` configuration (ethernet + DHCP), this configuration adds +the ``curl`` HTTP client command (``system/curl`` on top of +``netutils/webclient``), SD card support (same as the ``sdcard`` configuration, +mounted manually) and a larger console line buffer (``CONFIG_LINE_MAX=256``) so +long URLs and JSON bodies are not truncated when typed at the NSH prompt. + +It implements a subset of the real ``curl`` options: ``-X`` (method), ``-H`` +(header), ``-d`` (request body, also ``-d @file``), ``-F name=@file`` +(multipart/form-data upload), ``-o`` (save the response to a file) and ``-v`` +(verbose). It is HTTP only (no HTTPS). For the full option semantics see the +curl manual page: https://curl.se/docs/manpage.html + +Mount the SD card (destination for downloads) and bring up the network:: + + nsh> mount -t vfat /dev/mmcsd0 /mnt + nsh> ifconfig + eth0 Link encap:Ethernet HWaddr 00:e0:de:ad:be:ef at RUNNING mtu 1486 + inet addr:192.168.15.3 DRaddr:192.168.15.1 Mask:255.255.255.0 + +Download a file and save it on the SD card with ``-o`` (a public HTTP test +service such as ``httpbin.org`` requires the gateway to have internet access):: + + nsh> curl -o /mnt/dl.json http://httpbin.org/json + curl: HTTP 200 + nsh> cat /mnt/dl.json + { + "slideshow": { + "author": "Yours Truly", + "title": "Sample Slide Show", + ... + } + } + + nsh> curl -o /mnt/1kb.bin http://httpbin.org/bytes/1024 + curl: HTTP 200 + nsh> curl -o /mnt/img.png http://httpbin.org/image/png + curl: HTTP 200 + nsh> ls -l /mnt/img.png + -rw-rw-rw- 8090 /mnt/img.png + +Send a JSON body with POST (``-d`` selects POST automatically; ``-H`` sets the +content type). The ``httpbin.org/post`` endpoint echoes back what it received:: + + nsh> curl -H Content-Type:application/json -d '{"temp":25.3,"hum":60}' http://httpbin.org/post + { + "data": "{\"temp\":25.3,\"hum\":60}", + "headers": { + "Content-Type": "application/json", + "Host": "httpbin.org", + ... + }, + "json": { + "hum": 60, + "temp": 25.3 + }, + "url": "http://httpbin.org/post" + } + curl: HTTP 200 + +Select a different HTTP method with ``-X``:: + + nsh> curl -X PUT -d '{"x":1}' http://httpbin.org/put + curl: HTTP 200 + +Upload a file with multipart/form-data (``-F name=@file``) and download it back +with ``-o`` (this example targets a local server that stores the file and serves +it again):: + + nsh> curl -F file=@/mnt/nuttx_logo.png "http://192.168.15.12:8000/api/projects/default/ota/upload?version=logo1" + {"id":3,"version":"logo1","filename":"nuttx_logo.png","sha256":"ca278dcb...abed1ba","size_bytes":40343}curl: HTTP 201 + nsh> curl -o /mnt/logo_back.png http://192.168.15.12:8000/api/api/ota/default/logo1/nuttx_logo.png + curl: HTTP 200 + nsh> ls -l /mnt + -rw-rw-rw- 40343 nuttx_logo.png + -rw-rw-rw- 40343 logo_back.png + +.. note:: + + The webclient transfer buffer is small and the request has a ~10 s timeout, + so prefer small files (a few KB up to ~100 KB). HTTPS is not supported; use + plain ``http://`` URLs only. When there is no internet on the bench, point + ``curl`` at a server on the local network instead of a public test service. + qencoder -------- diff --git a/boards/arm/stm32h7/linum-stm32h753bi/configs/curl/defconfig b/boards/arm/stm32h7/linum-stm32h753bi/configs/curl/defconfig new file mode 100644 index 00000000000..6e12f2185ba --- /dev/null +++ b/boards/arm/stm32h7/linum-stm32h753bi/configs/curl/defconfig @@ -0,0 +1,107 @@ +# +# This file is autogenerated: PLEASE DO NOT EDIT IT. +# +# You can use "make menuconfig" to make any modifications to the installed .config file. +# You can then do "make savedefconfig" to generate a new defconfig file that includes your +# modifications. +# +# CONFIG_MMCSD_MMCSUPPORT is not set +# CONFIG_STANDARD_SERIAL is not set +CONFIG_ARCH="arm" +CONFIG_ARCH_BOARD="linum-stm32h753bi" +CONFIG_ARCH_BOARD_LINUM_STM32H753BI=y +CONFIG_ARCH_CHIP="stm32h7" +CONFIG_ARCH_CHIP_STM32=y +CONFIG_ARCH_CHIP_STM32H753BI=y +CONFIG_ARCH_CHIP_STM32H7=y +CONFIG_ARCH_CHIP_STM32H7_CORTEXM7=y +CONFIG_ARCH_STACKDUMP=y +CONFIG_ARMV7M_DCACHE=y +CONFIG_ARMV7M_DCACHE_WRITETHROUGH=y +CONFIG_ARMV7M_DTCM=y +CONFIG_ARMV7M_ICACHE=y +CONFIG_BOARD_LOOPSPERMSEC=43103 +CONFIG_BUILTIN=y +CONFIG_DEBUG_FEATURES=y +CONFIG_DEBUG_SYMBOLS=y +CONFIG_ETH0_PHY_KSZ8081=y +CONFIG_EXAMPLES_ALARM=y +CONFIG_FAT_DMAMEMORY=y +CONFIG_FAT_LCNAMES=y +CONFIG_FAT_LFN=y +CONFIG_FS_FAT=y +CONFIG_FS_PROCFS=y +CONFIG_FS_TMPFS=y +CONFIG_GRAN=y +CONFIG_GRAN_INTR=y +CONFIG_INIT_ENTRYPOINT="nsh_main" +CONFIG_INIT_STACKSIZE=4096 +CONFIG_INTELHEX_BINARY=y +CONFIG_LIBC_MEMFD_ERROR=y +CONFIG_LIBM=y +CONFIG_LINE_MAX=256 +CONFIG_MMCSD=y +CONFIG_MMCSD_SDIO=y +CONFIG_MMCSD_SDIOWAIT_WRCOMPLETE=y +CONFIG_MM_REGIONS=4 +CONFIG_NET=y +CONFIG_NETDB_DNSCLIENT=y +CONFIG_NETDB_DNSSERVER_IPv4ADDR=0x08080808 +CONFIG_NETDEV_PHY_DEBUG=y +CONFIG_NETINIT_DHCPC=y +CONFIG_NETINIT_DRIPADDR=0x08080808 +CONFIG_NETINIT_NOMAC=y +CONFIG_NETINIT_THREAD=y +CONFIG_NETUTILS_DHCPC=y +CONFIG_NETUTILS_DISCOVER=y +CONFIG_NETUTILS_TELNETD=y +CONFIG_NETUTILS_WEBCLIENT=y +CONFIG_NET_ARP_IPIN=y +CONFIG_NET_BROADCAST=y +CONFIG_NET_ETH_PKTSIZE=1500 +CONFIG_NET_ICMP_SOCKET=y +CONFIG_NET_IGMP=y +CONFIG_NET_ROUTE=y +CONFIG_NET_STATISTICS=y +CONFIG_NET_TCP=y +CONFIG_NET_UDP=y +CONFIG_NSH_BUILTIN_APPS=y +CONFIG_NSH_DISABLE_IFUPDOWN=y +CONFIG_NSH_FILEIOSIZE=512 +CONFIG_NSH_READLINE=y +CONFIG_PREALLOC_TIMERS=4 +CONFIG_RAM_SIZE=245760 +CONFIG_RAM_START=0x20010000 +CONFIG_RAW_BINARY=y +CONFIG_READLINE_CMD_HISTORY=y +CONFIG_READLINE_TABCOMPLETION=y +CONFIG_RR_INTERVAL=200 +CONFIG_RTC_ALARM=y +CONFIG_RTC_DATETIME=y +CONFIG_RTC_DRIVER=y +CONFIG_SCHED_HPWORK=y +CONFIG_SCHED_WAITPID=y +CONFIG_SDMMC1_SDIO_MODE=y +CONFIG_START_DAY=6 +CONFIG_START_MONTH=12 +CONFIG_START_YEAR=2011 +CONFIG_STM32_ETHMAC=y +CONFIG_STM32_HSI48=y +CONFIG_STM32_PHYSR=30 +CONFIG_STM32_PHYSR_100FD=0x6 +CONFIG_STM32_PHYSR_100HD=0x2 +CONFIG_STM32_PHYSR_10FD=0x5 +CONFIG_STM32_PHYSR_10HD=0x1 +CONFIG_STM32_PHYSR_ALTCONFIG=y +CONFIG_STM32_PHYSR_ALTMODE=0x7 +CONFIG_STM32_PWR=y +CONFIG_STM32_RMII_MCO1=y +CONFIG_STM32_RTC=y +CONFIG_STM32_SDMMC1=y +CONFIG_STM32_USART1=y +CONFIG_SYSTEM_CURL=y +CONFIG_SYSTEM_CURL_STACKSIZE=8192 +CONFIG_SYSTEM_NSH=y +CONFIG_SYSTEM_PING=y +CONFIG_TASK_NAME_SIZE=0 +CONFIG_USART1_SERIAL_CONSOLE=y