Patrick Barrett / libexositecoap

The (alpha of the) official Exosite library, CoAP version.

NOTE: This mirror repository may be out of date, check the main repo for changes. If there are any remind me to update this mirror.

This is an unstable alpha of the Official Exosite library, there are known issues with the port to this platform. You probably shouldn't use this library yet if you just want to get things done.

This version uses CoAP for the application protocol.

README.md@29:004c318e63fa, 2015-01-07 (annotated)

Committer:
Patrick Barrett
Date:
Wed Jan 07 14:20:56 2015 -0600
Revision:
29:004c318e63fa
Parent:
7:f9df43829cea 
added retry on network error

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Patrick 4:870843537eb0 1 **NOTICE: This library is not finished, do not depend on it for anything, it
Patrick Barrett 2:8ea8deb2653c 2 will have potentially significant bugs.**
Patrick Barrett 2:8ea8deb2653c 3
Patrick Barrett 2:8ea8deb2653c 4 # libexositecoap
Patrick Barrett 2:8ea8deb2653c 5
Patrick Barrett 2:8ea8deb2653c 6 This is the C library for interacting with the Exosite One Platform. It aims to
Patrick Barrett 2:8ea8deb2653c 7 be fast, efficient, and flexible. Platform operations are queued up and then
Patrick Barrett 2:8ea8deb2653c 8 performed with non-blocking calls so that your application can continue to do
Patrick Barrett 2:8ea8deb2653c 9 local processing while waiting for the network transactions to complete.
Patrick Barrett 2:8ea8deb2653c 10
Patrick Barrett 2:8ea8deb2653c 11 ## Status
Patrick Barrett 6:7f0440121941 12
Patrick Barrett 2:8ea8deb2653c 13 This is a very early release, there will be bugs. If you find one, please open
Patrick Barrett 2:8ea8deb2653c 14 an issue on https://github.com/exosite-labs/libexositecoap/issues. Pull requests
Patrick Barrett 2:8ea8deb2653c 15 are also highly encouraged. At some point in the future you will be required to
Patrick Barrett 2:8ea8deb2653c 16 show a test case that fails before your patch and succeeds after it, but there
Patrick Barrett 2:8ea8deb2653c 17 aren't any tests yet, so just describe the problem.
Patrick Barrett 2:8ea8deb2653c 18
Patrick Barrett 2:8ea8deb2653c 19 Because this is an alpha release, please don't use it in production.
Patrick Barrett 2:8ea8deb2653c 20 Backwards-incompatible changes will very likely have to be made when bugs are
Patrick Barrett 2:8ea8deb2653c 21 found, but you are highly encouraged to use it for testing. The examples do
Patrick Barrett 2:8ea8deb2653c 22 work and the changes to the interface won't be too substantial.
Patrick Barrett 2:8ea8deb2653c 23
Patrick Barrett 2:8ea8deb2653c 24 Only a limited set of the final features have been implemented. Currently, reads
Patrick Barrett 2:8ea8deb2653c 25 writes, and subscribes work. You can not yet activate or interact with content.
Patrick Barrett 6:7f0440121941 26
Patrick Barrett 2:8ea8deb2653c 27 The inline documentation is incomplete and is probably wrong in many places,
Patrick Barrett 2:8ea8deb2653c 28 don't pay too much attention to it. You should be able to figure out most of the
Patrick Barrett 2:8ea8deb2653c 29 usage from the examples and the function prototypes.
Patrick Barrett 2:8ea8deb2653c 30
Patrick Barrett 2:8ea8deb2653c 31 ## About
Patrick Barrett 2:8ea8deb2653c 32
Patrick Barrett 2:8ea8deb2653c 33 This library uses the concept of "operations" (ops) for all interactions with
Patrick Barrett 2:8ea8deb2653c 34 the OneP. One operation is a single read, write, or subscription of a single
Patrick Barrett 2:8ea8deb2653c 35 dataport. There are two classes of ops, single shot and sustained. Read and
Patrick Barrett 2:8ea8deb2653c 36 write are single shot operations. That means that you queue the operation then
Patrick Barrett 2:8ea8deb2653c 37 process until it either succeeds or fails. Subscribe is a sustained operation,
Patrick Barrett 2:8ea8deb2653c 38 that means that you queue it once then the library will do everything in it's
Patrick Barrett 2:8ea8deb2653c 39 power to keep it active.
Patrick Barrett 2:8ea8deb2653c 40
Patrick Barrett 2:8ea8deb2653c 41 ## Usage
Patrick Barrett 6:7f0440121941 42
Patrick Barrett 2:8ea8deb2653c 43 This section won't explain everything, at least not until we decide that the API
Patrick Barrett 2:8ea8deb2653c 44 is stable, see the examples folder for real uses.
Patrick Barrett 2:8ea8deb2653c 45
Patrick Barrett 2:8ea8deb2653c 46 ### Most Common Use
Patrick Barrett 6:7f0440121941 47
Patrick Barrett 2:8ea8deb2653c 48 You have to hold the memory for the ops, it's up to you if you want to use
Patrick Barrett 2:8ea8deb2653c 49 malloc, create an array of `exo_op`s then call `exo_op_init()` on that array to
Patrick Barrett 2:8ea8deb2653c 50 initialize it. Next add any sustained operations that you want. Then add any
Patrick Barrett 2:8ea8deb2653c 51 one-shot operations you want to call immediately. Once you have all the
Patrick Barrett 2:8ea8deb2653c 52 operations you want queued up, call `exo_operate()` until it returns `EXO_IDLE`,
Patrick Barrett 2:8ea8deb2653c 53 this means that it has nothing more to do and all of the queued single-shot
Patrick Barrett 2:8ea8deb2653c 54 operations have succeeded or failed and that all of the queued sustained
Patrick Barrett 2:8ea8deb2653c 55 sustained operations are in a waiting state and are not expecting any immediate
Patrick Barrett 2:8ea8deb2653c 56 responses. This is the time to do any operations that will take more than a
Patrick 4:870843537eb0 57 couple hundred milliseconds.