1// -*- mode:doc; -*-
2// vim: set syntax=asciidoc,tw=0:
3
4coap-client(5)
5==============
6:doctype: manpage
7:man source:   coap-client
8:man version:  @PACKAGE_VERSION@
9:man manual:   coap-client Manual
10
11NAME
12-----
13coap-client - CoAP Client based on libcoap
14
15SYNOPSIS
16--------
17*coap-client* [*-A* type1, _type2_ ,...] [*-t* type] [*-b* [num,]size]
18              [*-B* seconds] [*-e* text] [*-f* file] [*-m* method] [*-N*]
19              [*-o* file] [*-P* addr[:port]] [*-p* port] [*-s* duration]
20              [*-O* num,text] [*-T* token] [*-v* num] [*-a* addr] URI
21
22DESCRIPTION
23-----------
24*coap-client* is a CoAP client to communicate with 6LoWPAN devices via
25the protocol CoAP (RFC 7252) using the URI given as argument on the
26command line. The URI must have the scheme 'coap' (or 'coaps' when
27coap-client was built with support for secure communication). The URI's
28host part may be a DNS name or a literal IP address. Note that, for
29IPv6 address references, angle brackets are required (c.f. EXAMPLES).
30
31
32OPTIONS
33-------
34*-a* addr::
35   The local address of the interface that has to be used.
36
37*-b* [num,]size::
38   The block size to be used in GET/PUT/POST requests (value must be a
39   multiple of 16 not larger than 1024 as libcoap uses a fixed maximum
40   PDU size of 1400 bytes). If 'num' is present, the request
41   chain will start at block 'num'. When the server includes a Block2
42   option in its response to a GET request, coap-client will automatically
43   retrieve the subsequent block from the server until there are no more
44   outstanding blocks for the requested content.
45
46*-e* text::
47   Include text as payload (use percent-encoding for non-ASCII characters).
48
49*-f* file::
50   File to send with PUT/POST (use '-' for STDIN).
51
52*-m* method::
53   The request method for action (get|put|post|delete), default is 'get'.
54   (Note that the string passed to *-m* is compared case-insensitive.)
55
56*-o* file::
57   A filename to store data retrieved with GET.
58
59*-p* port::
60   The port to listen on.
61
62*-s* duration::
63   Subscribe to the resource specified by URI for the given 'duration' in
64   seconds.
65
66*-t* type::
67   Content format for given resource for PUT/POST. 'type' must be either
68   a numeric value reflecting a valid CoAP content format or a string
69   describing a registered format. The following registered content format
70   descriptors are supported, with alternative shortcuts given in
71   parentheses:
72
73     text/plain (plain)
74     application/link-format (link, link-format)
75     application/xml (xml)
76     application/octet-stream (binary, octet-stream)
77     application/exi (exi)
78     application/json (json)
79     application/cbor (cbor)
80
81*-v* num::
82   The verbosity level to use (default: 3, maximum is 9).
83
84*-A* type::
85   Accepted media types as comma-separated list of symbolic or numeric
86   values, there are multiple arguments as comma separated list
87   possible. 'type' must be either a numeric value reflecting a valid
88   CoAP content format or a string that specifies a registered format as
89   described for option *-t*.
90
91*-B* seconds::
92   Break operation after waiting given seconds (default is 90).
93
94*-N* ::
95   Send NON-confirmable message. If option *-N* is not specified, a
96   confirmable message will be sent.
97
98*-O* num,text::
99   Add option 'num' with contents of 'text' to the request.
100
101*-P* addr[:port]::
102   Address (and port) for proxy to use (automatically adds Proxy-Uri option
103   to request).
104
105*-T* token::
106   Include the 'token' to the request.
107
108EXAMPLES
109--------
110* Example
111----
112coap-client coap://coap.me
113----
114Query resource '/' from server 'coap.me' (via the GET method).
115
116* Example
117----
118coap-client -m get coap://[::1]/
119----
120Query on localhost via the 'GET' method.
121
122* Example
123----
124coap-client -m get coap://[::1]/.well-known/core
125----
126Quite the same, except on the resource '.well-known/core' on localhost.
127
128* Example
129----
130echo -n "mode=on" | coap-client -m put \
131coap://[2001:db8:c001:f00d:221:2eff:ff00:2704]:5683/actuators/leds?color=r -f-
132----
133Send text 'mode=on' to resource 'actuators/leds?color=r' on the endpoint with
134address '2001:db8:c001:f00d:221:2eff:ff00:2704' and port '5683'. Note that the
135port '5683' is the default port and isn't really needed to append.
136
137* Example
138----
139coap-client -m put coap://[fec0::3]/ck -T 3a -t binary -f to_upload
140----
141Put the contents of file 'to_upload' with content type 'binary' (i.e.
142application/octet-stream) into resource 'ck' on 'fec0::3' by usage of a token
143'3a' via the 'PUT' method.
144
145FILES
146------
147There are no configuration files.
148
149EXIT STATUS
150-----------
151*0*::
152   Success
153
154*1*::
155   Failure (syntax or usage error; configuration error; document
156   processing failure; unexpected error)
157
158BUGS
159-----
160Please report bugs on the mailing list for libcoap:
161libcoap-developers@lists.sourceforge.net
162
163AUTHORS
164-------
165The libcoap project <libcoap-developers@lists.sourceforge.net>
166