diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c32f36f..5b79d5a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,38 +3,50 @@ ---- -## Contributing Guide +# Awa LightweightM2M contributor guide. -### Reporting a bug. -So you have found a bug, or just generally an area which can be improved and wish to report it. +## Reporting issues and bugs. -Navigate to the "Issues" tab on the project github page https://github.com/FlowM2M/AwaLWM2M/issues and click the "New Issue" button. +If you discover a bug, or find an issue or area that you feel needs improvement: -When reporting your bug, please try and be as descriptive as possible. consider adding the following information. +* Navigate to the "Issues" tab on the project github page https://github.com/FlowM2M/AwaLWM2M/issues -``` -Description of the problem: +* Click the "New Issue" button. -Awa LWM2M Version or commit id: -Environment details (OS/Distribution etc): +When making your report, be as clear and concise as possible. Use the following list as a guide: -Reproduciblity/Frequency: -Steps to Reproduce/What you were doing when the bug occured: -Excepted Result: +* Describe the issue, and why you believe it's a problem. -Actual Result: +* Include the Awa LWM2M version or commit id. + +* Describe environment details (OS/distribution etc). + +* State how often the issue has occurred. + +* Describe the steps to take to uncover or reproduce the issue (if any). + +* Expected behaviour. + +* Actual behaviour. + +* Any additional infomation, log output etc. + + +---- + + +## Developer submissions. -Addition Infomation (log output etc) -``` ### Branching model. All Awa LWM2M development occurs on the master branch. Developers should only submit patches against the master branch. + ### Setting up your development machine. Configure your user name to be used by git: @@ -42,17 +54,54 @@ Configure your user name to be used by git: $ git config --global user.name "FirstName LastName" $ git config --global user.email "email@email.com" + ### Coding style. -The Awa LWM2M coding style guidelines can be found in the [Coding style guide](doc/coding_style.md) +The Awa LWM2M coding style guidelines can be found in the [coding style guide](doc/coding_style.md). + + + +### Commit messages. + +For the commit message, the following rules apply: + + * The first line should be a brief summary of the patch. + * Leave a blank line after the summary. + * Provide a detailed description of the change. + * Leave a blank line after the description. + * If the patch relates to an issue, add a line with 'Ref: ISSUE_ID'. + * Add a Gerrit 'Change-id' line. + * Add a Git 'Signed-off-by' line using ````git commit -s```` or ````git commit --sign-off```` (see *Signing your work* below). + + Example: + +```` + + Adds a new example feature xyz + + This patch adds example feature xyz. This feature merely acts + as an example of how to commit something to the project. + For real features this would contain some text + describing in detail what the new feature actually does. + + Ref: AWA-2131 + Change-Id: Id564ab1230913abf88123dff193b1231b1 + Signed-off-by: User Name + +```` + + ### Signing your work. -Awa LWM2M requires contributors to accept the Developer Certificate of Origin (DCO) (from developercertificate.org) +Awa LWM2M requires contributors to accept the Developer Certificate of Origin (DCO) from developercertificate.org. + +The sign-off is a single line at the end of your commit comment to certify that you either wrote the supplied code or otherwise have the right to pass on the code as open source. + + +Certifying your contribution asserts that *for the current submission* the following statement is true: -The sign-off is a single line at the end of your commit comment which certifies that you wrote the supplied code or otherwise have the right to pass it on the code as open-source. -It's pretty simple: if you can certify the following: ``` Developer Certificate of Origin @@ -92,43 +141,23 @@ By making a contribution to this project, I certify that: this project or the open source license(s) involved. ``` -Then you just add the following line to every git commit message to indicate that you accept the DCO: - -``` -Signed-off-by: User Name -``` - -If you set-up your user.name and user.email via git config, you can sign your commit automatically with git commit like so: - -``` -git commit --signoff -``` -### Commit messages. +To certify your submission just add the following line to *every* git commit message to indicate that you accept the above DCO: -For the commit message, the following rules apply: - * The first line should be a brief summary of the patch. - * Leave a blank line after the summary. - * Provide a detailed description of the change. - * Leave a blank line after the description. - * If the patch relates to an issue, add a line with 'Ref: ISSUE_ID'. - * Add a Gerrit 'Change-id' line. - * Add a Git 'Signed-off-by' line (using `git commit -s` or `git commit --sign-off`). +```` +Signed-off-by: User Name - Example: +```` - Adds a new example feature xyz +If you set-up your user.name and user.email via git config, you can sign your commit automatically with git commit: - This patch adds example feature xyz. This feature merely acts - as an example of how to commit something to the project. - For real features this would contain some text - describing in detail what the new feature actually does. - - Ref: AWA-2131 - Change-Id: Id564ab1230913abf88123dff193b1231b1 - Signed-off-by: User Name +```` +git commit --signoff +```` +---- +---- diff --git a/README.md b/README.md index 18e9e68..794ea15 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,13 @@ The LWM2M protocol has been designed to be highly efficient in terms of data tra Awa LWM2M is an implementation of the OMA Lightweight M2M protocol that provides a secure and standards compliant device management solution to simplify the development of M2M applications by providing an intuitive API that enables customization without the need for an intimate knowledge of M2M protocols. + +![Awa application overview](doc/Awa_application_overview.png) + + Awa LWM2M is a development suite that provides a number of components and tools which can be combined in various ways depending on requirement. For example: + * When running on a larger Linux based device, Awa LWM2M can be deployed as a series of daemons that interact with your application via the libawa library and associated API. * For more constrained devices, your application code can be built against the constrained device centric API and compiled along with the Awa LWM2M client code into a binary to be deployed on your device. @@ -28,59 +33,55 @@ The easiest way to get started with Awa LWM2M is on a Linux PC. The following i Firstly, to obtain a copy of the Awa LWM2M source code: - 1. Sign up for a Github account + * Sign up for a Github account - 2. Install Git + * Install Git: ```` sudo apt-get install git ```` -``` - sudo apt-get install git -``` + * Clone the repository: ```` git clone https://github.com/FlowM2M/AwaLWM2M.git ```` - 3. Clone the repository -``` - git clone https://github.com/FlowM2M/AwaLWM2M.git -``` -Further instructions can be found in the [Getting started guide](doc/starters_guide.md). +Further information can be found in the [Quick start guide](doc/starters_guide.md). ---- ### Documentation. -Awa LWM2M documentation is available both at a general level (project information, user and developer guides), and a techinical level (the API guide). All documentation is available in this repository. The *doc* directory contains information relating the project in general, and the *api/doc* directory contains the lower level documentation for the Awa API. +Awa LWM2M documentation is available both at a general level (project information, user and developer guides), and a techinical level (the API guide). All documentation is available in this repository. The *doc* directory contains information relating to the project in general, and the *api/doc* directory contains the lower level documentation for the Awa API. -#### General documentation. +Note that for our purposes the terms *user* and *developer* have the following definitions: + +* *User* - An M2M application developer who uses the tools and libraries supplied by this project as the foundation of, or enhancement to, their own M2M application. +* *Developer* - A developer who develops for and contributes to the Awa LightweightM2M project. -* For build instructions see the [Getting started guide](doc/starters_guide.md) -* Examples of how to use the tools can be found in the [User guide](doc/userguide.md) -* For developers, an overview of the system can be found in the [Developer guide](doc/developer_guide.md) -* Information regarding the testing framework, can be found in the [Testing](doc/testing.md) guide. + +#### General documentation. + +* For project users: + * For build instructions, see the [Quick start guide](doc/starters_guide.md). + * Examples of how to use the tools can be found in the [User guide](doc/userguide.md). +* For contributing developers: + * An overview of the system can be found in the [Developer guide](doc/developer_guide.md). + * Information regarding the testing framework, can be found in the [Testing](doc/testing.md) guide. #### API guide. The Awa API documentation is available as a Doxygen presentation which is generated via the following process. - 1. Install [Doxygen ](http://www.stack.nl/~dimitri/doxygen/download.html) + 1. Install [Doxygen ](http://www.stack.nl/~dimitri/doxygen/download.html): ```` sudo apt-get install doxygen```` -``` - sudo apt-get install doxygen -``` + 2. Generate the documentation: ```` make docs```` - 2. Generate the documentation -``` - make docs -``` - The output can be found in the api/doc/html directory and viewed by opening index.html with your web browser. +The output can be found in the api/doc/html directory and viewed by opening index.html with your web browser. -For convenience you can also find the latest version of this documentation [here]() +For convenience you can also find the latest version of this documentation [here](). ---- ### Contributing. -We welcome all contributions to this project and we give credit where it's due. Anything from enhancing functionality, to improving documentation and bug reporting - it's all good. +We welcome all contributions to this project and we give credit where it's due. Anything from enhancing functionality to improving documentation and bug reporting - it's all good. -Find out more in the [Contributing guide](CONTRIBUTING.md). +Find out more in the [contributor guide](CONTRIBUTING.md). ### Credits. @@ -96,9 +97,9 @@ We would also like to acknowledge and thank the authors of the following project ### License information. -* All code and documentation developed by Imagination Technologies Limited is licensed under the [BSD 3-clause license](LICENSE) -* LibCoAP by Olaf Bergmann is licensed under the GNU General Public License (GPL), Version 2 or higher, OR the simplified BSD license -* Jsmn by Serge A. Zaitsev is licensed under the MIT license +* All code and documentation developed by Imagination Technologies Limited is licensed under the [BSD 3-clause license](LICENSE). +* LibCoAP by Olaf Bergmann is licensed under the GNU General Public License (GPL), Version 2 or higher, OR the simplified BSD license. +* Jsmn by Serge A. Zaitsev is licensed under the MIT license. ---- diff --git a/api/.gitignore b/api/.gitignore old mode 100755 new mode 100644 diff --git a/api/python/ipc.py b/api/python/ipc.py old mode 100755 new mode 100644 diff --git a/doc/Awa_application_overview.png b/doc/Awa_application_overview.png new file mode 100644 index 0000000..b7d2cb2 Binary files /dev/null and b/doc/Awa_application_overview.png differ diff --git a/doc/Awa_client_API_structure.png b/doc/Awa_client_API_structure.png new file mode 100644 index 0000000..23cc995 Binary files /dev/null and b/doc/Awa_client_API_structure.png differ diff --git a/doc/LWM2M_object_referencing.png b/doc/LWM2M_object_referencing.png new file mode 100644 index 0000000..3ce7679 Binary files /dev/null and b/doc/LWM2M_object_referencing.png differ diff --git a/doc/coding_style.md b/doc/coding_style.md index 4361c39..374f0df 100644 --- a/doc/coding_style.md +++ b/doc/coding_style.md @@ -1,5 +1,5 @@ -![](doc/img.png) +![](img.png) ---- @@ -9,6 +9,11 @@ ## Coding style guide. +It's important to that coding style remains consistent throughout the project to ensure that all contributors and project administrators are able to easily decipher code blocks, comments, syntax etc. +Always consider that another contributor may one day continue to build on your submissions. Make it easy for them by adopting the style outlined below. + +### General layout. + The sample code below illustrates the preferred use of indentation, bracing and white space: ```` @@ -60,7 +65,7 @@ typedef struct **Notes.** * A structure type definition doesn't usually need both a structure name and typedef name (a struct name is not given in the above example). One possible exception to this rule is where the typedef name is declaring a structure-pointer type. -* The use of suffix *_e* in enums is not preferred. +* The use of suffix *_e* in enums is discouraged. * To avoid namespace problems in 'C' each value should be prefixed by the enum name. For example: ```` typedef enum @@ -88,11 +93,11 @@ Bitfields also have a code size and performance overhead due to the need to be p Structure field names should use Pascal casing (e.g. ThisPerson.Age). -### Header Files. +### Header files. All public functions, variables and definitions must be declared in a header file. Most .c modules should have a corresponding .h file to be included (both within the module and elsewhere). It is poor form to make the compiler try to guess how to resolve undeclared function calls in other modules. -## Commenting. +### Code commenting. Single line comments should use *//*. For example: ```` void MyFunction(void) @@ -107,7 +112,7 @@ void MyFunction(void) } ```` -Similarly multi-line comments within a function should be formatted like this: +Similarly, multi-line comments within a function should be formatted like this: ```` void AwaTask(void *parameters) { @@ -137,7 +142,7 @@ AwaString GetNextEntryFromProcessingQueue() } ```` -### Good/Bad Coding Practise. +### Good coding practise. * Ideally functions should have a single exit point. The use of multiple return points is dangerous and makes it harder to read the code. Always consider what will happen if someone needs to append code to your function. * Where possible definitions should be used rather than raw values, e.g. use *AllocMessageBuf(MAX_MESSAGE_SIZE)* rather than *AllocMessagBuf(1024)*. This ensures that all code sharing the same defined value will still work if the 'magic' value is updated. diff --git a/doc/developer_guide.md b/doc/developer_guide.md index 9f0d9b1..3c51e3c 100644 --- a/doc/developer_guide.md +++ b/doc/developer_guide.md @@ -1,5 +1,5 @@ -![](doc/img.png) +![](img.png) ---- @@ -7,34 +7,38 @@ ## Developer guide. +This guide is intended for developers who aim to contribute to the Awa LightweightM2M project. Developers who intend only to use the Awa LightweightM2M tools in their own M2M applications are referred to the [Awa LightweightM2M user guide](userguide.md). - -## Introduction. +### Introduction. OMA LightweightM2M (LWM2M) facilitates standardised communication between devices and management applications. LWM2M is built on a request/response protocol called Constrained Application Protocol (CoAP), which is similar to HTTP. A CoAP server hosts a number of resources that can be read from and written to by a CoAP client. LWM2M makes use of CoAP resources to group information into instances of standard and registry-defined objects which are defined to provide common device management functions such as location, software upgrades, and network configuration. As LWM2M operations are carried via CoAP requests, each request specifies an **endpoint** that corresponds to a particular resource. -LWM2M also provides a "bootstrap" mechanism, which helps a client to locate and connect to a management server in a secure manner. A trusted Bootstrap server may be configured with appropriate security credentials for one or more management servers. Clients connecting to the Bootstrap server are then provided with these credentials to enable registration with the relevant management server. +LWM2M also provides a *bootstrap* mechanism, which helps a client to locate and connect to a management server in a secure manner. A trusted bootstrap server may be configured with appropriate security credentials for one or more management servers. Clients connecting to the bootstrap server are then provided with these credentials to enable registration with the relevant management server. -LWM2M makes use of an *Object/Object Instance/Resource* (OIR) model to represent information. Objects are constructed from individual resource definitions, and each instance of an object is called an *Object Instance*. Refer to section 6.1 of the LWM2M technical specification for details http://technical.openmobilealliance.org/Technical/technical-information/release-program/current-releases/oma-lightweightm2m-v1-0 +LWM2M makes use of an *Object/Object Instance/Resource* (OIR) model to represent information. Objects are constructed from individual resource definitions, and each instance of an object is called an *Object Instance*. + +![OIR model](LWM2M_object_referencing.png) + +Refer to section [6.1 of the LWM2M technical specification](http://technical.openmobilealliance.org/Technical/technical-information/release-program/current-releases/oma-lightweightm2m-v1-0) for details. Awa LightWeightM2M is an implementation of OMA LWM2M written in C. It incorporates both server and client functionality and provides APIs for both. Typically, the client or server runs as a standalone Linux process (a "daemon") and an application uses the API library to access and modify resources across an inter-process communication (IPC) interface. This decoupling of the API from the main functionality allows other languages to make use of the daemons by implementing the IPC protocol. **ADD DIAGRAM** -## License. -Awa LightWeightM2M source code is made available by Imagination Technologies Limited under the standard 3-clause BSD license. Please see [LICENSE](../LICENSE) for details. +### License. +Awa LightWeightM2M source code is made available by Imagination Technologies Limited under the standard 3-clause BSD license described [here.](https://www.tldrlegal.com/l/bsd3) -## Contributing to Awa LightWeightM2M. +### Contributing to Awa LightWeightM2M. Contributions to the Awa project are welcome and there are many ways to help, by submitting bug reports for example, or making feature requests, code changes or documentation edits. -To ensure that the codebase remains easy to understand, maintain and improve, all contributions should adhere to the [Coding Style guidelines](doc/coding_style.md). -A comprehensive collection of unit tests is being developed and maintained to ensure that new contributions do not break existing functionality. All code submissions should be accompanied by one or more relevant unit tests, implemented within the existing unit test framework as described in the *Testing* section below. +To ensure that the codebase remains easy to understand, maintain and improve, all contributions should adhere to the [coding style guide](doc/coding_style.md). +A comprehensive collection of unit tests is being developed and maintained to ensure that new contributions do not break existing functionality. All code submissions should be accompanied by one or more relevant unit tests, implemented within the existing unit test framework as described in the [*Testing*](developer_guide.md#testing) section below. For further details on contributing go [here](../CONTRIBUTING.md). -## Design overview. -This section provides information about the structure of the codebase, and how the components interact. +### Design overview. +This section provides information about the structure of the codebase and how the components interact. The codebase is divided into the following parts: @@ -43,7 +47,7 @@ The codebase is divided into the following parts: * Bootstrap server * API -The Client, Server and Bootstrap server are implemented as Linux processes. Typically these run as *daemons*, detached from a parent console, which may be configured to automatically run when the host starts up. For example, a Linux gateway may automatically start the Server so that constrained devices are able to register as soon as the gateway becomes available. +The Client, Server and Bootstrap server are implemented as Linux processes. Typically these run as *daemons*, detached from a parent console, which may be configured to automatically run when the host starts up. For example, a Linux gateway may automatically start the server so that constrained devices are able to register as soon as the gateway becomes available. The API is provided as a linkable library, to be incorporated into a user program. The API has three parts: @@ -57,34 +61,11 @@ The Static client API is designed for cases where the configuration will not cha ### The client API. -The client API consists of the *client core*, which coordinates the IPC layer (for communication with the Client API), static API, serialiser/deserialiser (*serdes*), CoAP, definition registry, data storage (*object tree*) and observer registry. -```` - CoAP static API IPC -----------------> API - | | | - libcoap | | - |---coap abstraction | xml handlers, xml serdes - | | | - |---lwm2m client core---| - | - |---- serdes - | |---- tlv - | |---- plain text - | |---- opaque - | |---- json - | - |---- endpoints - |---- object tree - |---- definition registry - | |---- security object - | |---- server object - | |---- object store - | - |---- observers - |---- attributes -```` - - -**The client core.** +The client API consists of the *client core*, which coordinates the IPC layer (for communication with the client API), the static API, serialiser/deserialiser (*serdes*), CoAP, definition registry, data storage (*object tree*) and observer registry. + +![Awa client API structure](Awa_client_API_structure.png) + +#### The client core. The core is the layer that pulls all of the components together. It defines a number of functions called to handle requests from the CoAP layer, static API and the IPC interface. @@ -98,22 +79,22 @@ Additionally, an access control check is made to ensure that the requested opera Most resource read/write handlers are handled by the object store which acts as a generic storage mechanism. The standard server and security objects each have their own specialised handlers. -**The definition registry.** +#### The definition registry. The definition registry stores definitions for all objects and resources within the system. -There are two kinds of definitions: -* Resource definitions, which define a single resource that acts as a container for a LWM2M data type. -* Object definitions, which may contain one or more resource definitions, hold information such as whether multiple instances of the object can be created, or whether an object instance is *mandatory* or *optional*, and contain various function pointers which map its operations (Write/Read etc) onto the appropriate handlers. +There are two types of definition: +* **The resource definition**, which defines a single resource that acts as a container for a LWM2M data type. +* **The object definition**, which may contain one or more resource definitions, holds information such as whether multiple instances of the object can be created, or whether an object instance is *mandatory* or *optional*, and may contain various function pointers which map its operations (Write/Read etc) onto the appropriate handlers. -*Note that the resources themselves do not exist until the object is instantiated.* +*Note that defining a resource does not instantiate it. A resource does not exist until its parent object is instantiated.* -### The CoAP abstraction layer. +#### The CoAP abstraction layer. The CoAP abstraction layer hides the specifics of a CoAP library's interface and provides a common interface that can be used by the core. -### Serdes. +#### Serdes. There is a serialiser and deserialiser (serdes) for each of the data formats supported by the LWM2M protocol and implemented by Awa LightweightM2M. The supported data formats are: * Plain Text @@ -178,7 +159,7 @@ TODO ## Testing. - Awa LWM2M was developed alongside a comprehensive test suite, implemented within the Google Test framework. Tests are written in C++ and compile as part of one of several "test runner" applications: +Awa LWM2M was developed alongside a comprehensive test suite, implemented within the Google Test framework. Tests are written in C++ and compile as part of one of several "test runner" applications: * test_core_runner executes tests related to Client and Server daemon components. * test_api_runner executes tests related to Client and Server API components, including top-level tests involving multiple daemons. @@ -187,5 +168,3 @@ TODO - - diff --git a/doc/starters_guide.md b/doc/starters_guide.md index 1386f8c..6add5c3 100644 --- a/doc/starters_guide.md +++ b/doc/starters_guide.md @@ -1,50 +1,80 @@ -![](doc/img.png) +![Imagination Technologies Limited logo](img.png) ---- -## Getting Started Guide. + +# Awa LightweightM2M. + + + +---- + +## Quick start guide. + ### Building the code. + #### Building under Linux. - Install the dependencies +Install the dependencies: + ``` sudo apt-get update - sudo apt-get install build-essential gcc git mercurial python cmake python-nose python-lxml + sudo apt-get install build-essential gcc git mercurial python cmake python-nose python-lxml ``` - Run make in the root directory of the Awa LWM2M repository +Run make in the root directory of the Awa LWM2M repository + + +````$ make```` + + +This will produce the following executable files: - $ make +* build/core/src/client/awa_clientd +* build/core/src/client/awa_serverd +* build/core/src/client/awa_bootstrapd - This will produce the following executable files: + +For usage information see the [User guide](userguide.md) - build/core/src/client/awa_clientd - build/core/src/client/awa_serverd - build/core/src/client/awa_bootstrapd - For usage information see the [User guide](doc/userguide.md) +#### The cmake build. -#### The cmake Build. - The build can be created out-of-source, such that all build artefacts are placed in a dedicated directory. +The build can be created out-of-source, such that all build artefacts are placed in a dedicated directory. - First, create a suitable directory for the build output: - $ mkdir build +First, create a suitable directory for the build output: - From this directory, run cmake, passing the path to the root directory of the repository as a parameter: + +````$ mkdir build ```` + + +From this directory, run cmake, passing the path to the root directory of the repository as a parameter: +```` $ cd build $ cmake .. +```` + + +This generates a Makefile in the build directory, which can be run to generate the build artefacts: + + +````$ make ```` - This generates a Makefile in the build directory, which can be run to generate the build artefacts: - $ make +Once the build is complete you may optionally *install* the resulting binaries to a specified directory, for example: - Once the build is complete you may optionally "install" the resulting binaries to a specified directory, for example: - $ make DESTDIR=./install install +````$ make DESTDIR=./install install ```` + + +---- + +---- + diff --git a/doc/testing.md b/doc/testing.md index 2f922c2..39fff6d 100644 --- a/doc/testing.md +++ b/doc/testing.md @@ -1,92 +1,113 @@ -![](doc/img.png) +![](img.png) ---- # Awa LightweightM2M. +---- -## Testing - -### Awa API Testing - - The Awa API is covered by a comprehensive test suite based on Google Test. - - It is possible to run individual tests for debugging purposes, using the --gtest_filter flag. Wildcards (*) can be passed in order to run multiple tests/suits that match the filter. (eg. --gtest_filter=TestGet.\* to run all tests in the TestGet suite). Refer to the gtest advanced guide for further details. - - Additional output can be displayed by enabling a high log level. The option --logLevel can be passed a value between 1 and 4, where 4 is the most verbose. - - Running the tests with Valgrind is highly recommended to ensure no memory leaks are introduced. - -Examples: - - Note: replace TestSuite.TestName with the test suite and test you wish to run. - - To run a single test: - - $ (cd build && make test_api_runner VERBOSE=1 && valgrind --leak-check=full --show-leak-kinds=all --track-origins=yes apiv2/tests/test_api_runner --logLevel 1 --gtest_filter=TestSuite.TestName) +## Testing. - To run a single test specifying an already-running client: +### Awa API testing. - $ (cd build && make test_api_runner VERBOSE=1 && valgrind --leak-check=full --show-leak-kinds=all --track-origins=yes apiv2/tests/test_api_runner --logLevel 1 --gtest_filter=TestSuite.TestName --clientIpcPort 12345) +The Awa API is covered by a comprehensive test suite based on Google Test. - To run a test specifying an already-running server: +It is possible to run individual tests for debugging purposes, using the *--gtest_filter* flag. Wildcards (*) can be passed in order to run multiple tests/suits that match the filter. - # a custom debug bootstrap file is used so the client daemons connect to the correct server port, refer to api/tests/bootstrap-debug.config. - $ (cd build && make test_api_runner VERBOSE=1 && valgrind --leak-check=full --show-leak-kinds=all --track-origins=yes api/tests/test_api_runner --logLevel 1 --gtest_filter=TestSuite.TestName --serverIpcPort 54321 --bootstrapConfig ../api/tests/bootstrap-debug.config) +For example: ```` --gtest_filter=TestGet.\* ```` runs all tests in the TestGet suite. -### Awa Core Testing +Refer to the gtest advanced guide for further details. - To run a test specifying an already-running server: +Additional output can be displayed by enabling a high log level. The option *--logLevel* can be passed a value between 1 and 4, where 4 is the most verbose. - $ (cd build && make test_src_runner VERBOSE=1 && valgrind --leak-check=full --show-leak-kinds=all --track-origins=yes src/tests/test_src_runner --logLevel 1 --gtest_filter=TestSuite.TestName) +Running the tests with [*Valgrind*](http://valgrind.org/docs/manual/quick-start.html) is highly recommended to ensure that no memory leaks are introduced. -### Awa Tools Testing +Examples: - Tests are provided that run against the supplied LWM2M tools. These tests help ensure that the tools perform correctly and produce the expected output, including error codes. These tests are written in Python and depend on the nosetests package. +**Note.** Replace *TestSuite.TestName* with the test suite and test you want to run. - For debian-based systems run: +To run a single test: +```` +$ (cd build && make test_api_runner VERBOSE=1 && valgrind --leak-check=full --show-leak-kinds=all --track-origins=yes apiv2/tests/test_api_runner --logLevel 1 --gtest_filter=TestSuite.TestName) +```` - $ sudo apt-get install python-nose +To run a single test specifying an already-running client: +```` +$ (cd build && make test_api_runner VERBOSE=1 && valgrind --leak-check=full --show-leak-kinds=all --track-origins=yes apiv2/tests/test_api_runner --logLevel 1 --gtest_filter=TestSuite.TestName --clientIpcPort 12345) +```` - Then, run the tests using: +To run a test specifying an already-running server: +```` +# a custom debug bootstrap file is used so the client daemons connect to the correct server port, refer to api/tests/bootstrap-debug.config. +$ (cd build && make test_api_runner VERBOSE=1 && valgrind --leak-check=full --show-leak-kinds=all --track-origins=yes api/tests/test_api_runner --logLevel 1 --gtest_filter=TestSuite.TestName --serverIpcPort 54321 --bootstrapConfig ../api/tests/bootstrap-debug.config) +```` - $ cd tools/tests - $ ./run_tests +### Awa core testing. -### SDK Testing +To run a test specifying an already-running server: +```` +$ (cd build && make test_src_runner VERBOSE=1 && valgrind --leak-check=full --show-leak-kinds=all --track-origins=yes src/tests/test_src_runner --logLevel 1 --gtest_filter=TestSuite.TestName) +```` - Awa LWM2M contains a number of unit test cases. These can be executed by running the following command from the root of the repository: +### Awa tools testing. - $ make tests +Tests are provided that run against the supplied LWM2M tools. These tests help ensure that the tools perform correctly and produce the expected output, including error codes. These tests are written in Python and depend on the [*nosetests*](http://pythontesting.net/framework/nose/nose-introduction/) package. - Google Test (gtest) is used to write C++ tests against Core and API code. These can be run separately with: +For debian-based systems run: +```` +$ sudo apt-get install python-nose +```` - $ make gtest_tests +Then, run the tests using: +```` +$ cd tools/tests +$ ./run_tests +```` - Individual tests can be run by specifying them on the command line as an argument to TEST_FILTER: +### SDK testing. - $ make gtest_tests TEST_FILTER=ObjectStoreInterfaceTestSuite.test_WriteAndReadSingleResource +Awa LWM2M contains a number of unit test cases. These can be executed by running the following command from the root of the repository: +```` +$ make tests +```` - Multiple tests can be run by separating them with a colon character: +Google Test (gtest) is used to write C++ tests against core and API code. These can be run separately with: +```` +$ make gtest_tests +```` - $ make gtest_tests TEST_FILTER=ObjectStoreInterfaceTestSuite.test_WriteAndReadSingleResource:TlvTestSuite.test_serialise_float32 +Individual tests can be run by specifying them on the command line as an argument to TEST_FILTER: +```` +$ make gtest_tests TEST_FILTER=ObjectStoreInterfaceTestSuite.test_WriteAndReadSingleResource +```` +Multiple tests can be run by separating them with a colon: +```` +$ make gtest_tests TEST_FILTER=ObjectStoreInterfaceTestSuite.test_WriteAndReadSingleResource:TlvTestSuite.test_serialise_float32 +```` Groups of tests can be run with a wildcard (asterisk) character: +```` +$ make gtest_tests TEST_FILTER=FlowDmLowBasicTestSuite.test_encode_and_extract_* # runs all tests in this suite beginning with "test_encode_and_extract_" +$ make gtest_tests TEST_FILTER=FlowDmLowBasicTestSuite.* # runs all tests in this suite +```` + +Debugging tests can be run with the *gdb_tests* target. This invokes *gdb* when a test fails, to assist with debugging: +```` +$ make gdb_tests +```` + +Memory-leak tests can be run with the valgrind_tests target. This invokes *Valgrind* to discover and report memory leaks: +```` +$ make valgrind_tests +```` + +Some tests spawn and tear down instances of the LWM2M client and/or server daemon. Sometimes it is useful to run the tests against a standalone daemon, for example when debugging the daemon. Note that the standalone daemon is not torn down between tests, so some tests may not behave properly as daemon state is retained between tests. +```` +$ build/core/src/client/awa_clientd --ipcPort=22222 +$ make tests TEST_OPTIONS=--clientIpcPort=22222 +```` - $ make gtest_tests TEST_FILTER=FlowDmLowBasicTestSuite.test_encode_and_extract_* # runs all tests in this suite beginning with "test_encode_and_extract_" - - $ make gtest_tests TEST_FILTER=FlowDmLowBasicTestSuite.* # runs all tests in this suite - - Debugging tests can be run with the gdb_tests target. This invokes gdb when a test fails, to assist with debugging: - - $ make gdb_tests - - Memory-leak tests can be run with the valgrind_tests target. This invokes valgrind to discover and report memory leaks: - - $ make valgrind_tests - - Some tests spawn and tear down instances of the LWM2M client and/or server daemon. Sometimes it is useful to run the tests against a standalone daemon, for example when debugging the daemon. Note that the standalone daemon is not torn down between tests, so some tests may not behave properly as daemon state is retained between tests. +---- +---- - $ build/core/src/client/awa_clientd --ipcPort=22222 - $ make tests TEST_OPTIONS=--clientIpcPort=22222 diff --git a/doc/userguide.md b/doc/userguide.md index 2c192e7..f55d346 100644 --- a/doc/userguide.md +++ b/doc/userguide.md @@ -1,32 +1,95 @@ -![](doc/img.png) + +![](img.png) ---- # Awa LightweightM2M. ## User guide. +This document is aimed at application developers who are using the Awa LightweightM2M libraries and tools as a foundation, or enhancement of their own M2M applications. + +Developers who aim to contribute to the Awa LightweightM2M project are referred to the [contributor guide](../CONTRIBUTING.md) and the [developer guide](developer_guide.md). + +---- + + + ### Contents. -* [Introduction.](userguide.md#introduction) +* [Introduction.](userguide.md#introduction) +* [The LWM2M object model.](userguide.md#the-lwm2m-object-model) * [The LWM2M client.](userguide.md#the-lwm2m-client) - * [The Awa client daemon](userguide.md#the-awa-client-daemon) + * [The Awa client daemon.](userguide.md#the-awa-client-daemon) + * [Using the LWM2M client.](userguide.md#using-the-LWM2M-client) + * [The Awa API.](userguide.md#the-awa-api) + * [API options.](userguide.md#common-options) + * [Creating a new object definition.](userguide.md#creating-a-new-object-definition) + * [Discovering a device's object and resource definitions.](userguide.md#discovering-a-device's-object-and-resource-definitions) + * [Setting resource values.](userguide.md#setting-resource-values) + * [Retrieving a resource value.](userguide.md#retrieving-a-resource-value) + * [Subscribing to a change of resource value.](userguide.md#subscribing-to-a-change-of-resource-value) + * [Deleting a resource.](userguide.md#deleting-a-resource) * [The LWM2M server.](userguide.md#the-lwm2m-server) - * [The Awa server daemon](userguide.md#the-awa-server-daemon) + * [The Awa server daemon.](userguide.md#the-awa-server-daemon) + * [Awa server API tools.](userguide.md#awa-server-api-tools) + * [Listing registered clients.](userguide.md#listing-registered-clients) + * [Creating a server object definition.](userguide.md#creating-a-server-object-definition) + * [Writing a value to a resource on a registered client.](userguide.md#writing-a-value-to-a-resource-on-a-registered-client) + * [Reading a resource value from a registered client.](userguide.md#reading-a-resource-value-from-a-registered-client) + * [Deleting an object instance from a registered client.](userguide.md#deleting-an-object-instance-from-a-registered-client) + * [Observing a resource on a registered client.](userguide.md#observing-a-resource-on-a-registered-client) + * [Executing a resource on a registered client.](userguide.md#executing-a-resource-on-a-registered-client) + * [Write attribute values of a resource or object instance on a registered client.](userguide.md#write-attribute-values-of-a-resource-or-object-instance-on-a-registered-client) * [The LWM2M Bootstrap server.](userguide.md#the-lwm2m-bootstrap-server) - * [The Awa bootstrap server daemon](userguide.md#the-awa-bootstrap-server-daemon) - + * [The Awa bootstrap server daemon.](userguide.md#the-awa-bootstrap-server-daemon) ---- ### Introduction. + + +![Awa application overview](Awa_application_overview.png) + + LWM2M is a protocol that allows client resources to be accessed by a server. In the Awa library the client and server are daemons (individual processes), each having its own respective API interface over an inter-process communication interface (IPC). The client API is for use exclusively with the client daemon, and the server API is for use exclusively with the server daemon. A suite of tools is provided to exercise the main functionality of the API for both the client and server. Later sections describe the configuration of the Awa client and server daemons, along with examples of tools use. A bootstrap server daemon is also provided that implements the LWM2M bootstrapping protocol which instructs LWM2M clients which LWM2M server to connect to. Later sections describe the configuration of the Awa bootstrap server. +### The LWM2M object model. + +---- + +![LWM2M object model](LWM2M_object_referencing.png) + +---- + + +LWM2M is based on an object model such that: +* An object is defined to represent a device or client application, or a LWM2M device management function. +* Each object is defined on both the client and the server. +* The client hosted object holds the current status of the device and resources are mapped directly to device functions (e.g. temperature sensor or tilt switch). +* The server hosted object reflects a device's status on the server. The server has the tools to query resource values for any client directly. +* One or more instances of an object may exist simultaneously but each will have a unique instance identifier. +* An object is composed of one or more resources, grouped under a single object identifier. +* Each resource is fully described and is uniquely addressable within the object. +* The OMA has pre-defined objects suitable for most cases, but custom objects may still be defined for local use. +* One or more instances of a resource may exist simultaneously within an object but each will have a unique instance identifier. + +Object and resource identifiers are 16 bit integers. Object and resource *instance* identifiers are 8 bit integers. + +A resource instance is accessed via its parent object instance using a semantic approach: + +````{objectID}/{object instance}/{resource ID}/{resource instance}```` + +In the case where a single instance of an object and resource exists the address resolves to ````{objectID}/{ResourceID}```` + +Semantic addressing allows resources to be written to directly: ````1000/0/1/2='this value"```` + ---- + ### The LWM2M client. The LWM2M Client runs as a daemon and provides the core LWM2M functionality for: @@ -42,7 +105,7 @@ The client provides two interfaces: * An IPC interface which provides a mechanism for applications to talk to the daemon. -![Awa LWM2M client interfaces](doc/awa_client_interfaces.png) +![Awa LWM2M client interfaces](awa_client_interfaces.png) The IPC interface allows the end user application to define new objects and to perform Get/Set/Delete/Subscribe operations on the client. @@ -71,17 +134,14 @@ Example: ```` awa_clientd --port 6000 --endPointName client1 --bootstrap coap://0.0.0.0:2134 ```` -### Awa client daemon tools. - -should this be here? - ---- + ### The LWM2M server. The LWM2M server runs as a daemon which provides an interface to perform LWM2M operations on connected LWM2M clients. -![Awa LWM2M server interfaces](doc/Awa_LWM2M_server_interfaces.png) +![Awa LWM2M server interfaces](Awa_LWM2M_server_interfaces.png) The IPC interface allows the end user application to define new objects, list registered clients and perform Read/Write/Delete/Observe operations for a given LWM2M client registered with the server. Currently the IPC interface is implemented as a simple UDP channel, with an associated UDP port. It is recommended that only a single user application connect to the daemon's IPC interface at any time. @@ -89,7 +149,6 @@ Currently the IPC interface is implemented as a simple UDP channel, with an asso ### The Awa server daemon. - Usage: ````awa_serverd [options] ```` | options | description | @@ -111,12 +170,15 @@ Example: ````awa_serverd --interface eth0 --addressFamily 4 --port 5683 ```` For examples of how to use the LWM2M server with the LWM2M client see the *LWM2M client usage* section below. +---- + + ### The LWM2M Bootstrap server. The LWM2M Bootstrap server runs as a daemon which provides a mechanism to bootstrap LWM2M clients. -![](doc/Awa_LWM2M_bootstrap_server-interfaces.png) +![](Awa_LWM2M_bootstrap_server-interfaces.png) ### The Awa Bootstrap server daemon. @@ -162,406 +224,349 @@ DisableTimeout=86400 NotificationStoringWhenDisabledOrOffline=true ```` - * ServerURI specifies the address and port of the LWM2M server to which clients will be directed. - * SecurityMode is not yet supported. - * PublicKey is not supported. - * SecretKey is not supported. - * ServerID specifies the numerical ID of the LWM2M server used to associate security and server objects on the LWM2M client. - * HoldOffTime is not yet supported. - * ShortServerID specifies the numerical ID of the LWM2M server used to associate Security and Server objects on the LWM2M client. + * *ServerURI* specifies the address and port of the LWM2M server to which clients will be directed. + * *SecurityMode* is not yet supported. + * *PublicKey* is not supported. + * *SecretKey* is not supported. + * *ServerID* specifies the numerical ID of the LWM2M server used to associate security and server objects on the LWM2M client. + * *HoldOffTime* is not yet supported. + * *ShortServerID* specifies the numerical ID of the LWM2M server used to associate Security and Server objects on the LWM2M client. * Binding specifies the supported LWM2M binding modes for this server. Only "U" (UDP, non-queuing) is currently supported. - * LifeTime specifies the minimum time (in seconds) that the server will wait after receiving a registration or update from the client before terminating that registration. - * DefaultMinimumPeriod specifies the default minimum period of observations. - * DefaultMaximumPeriod specifies the default maximum period of observations, -1 represents an indefinite period. - * DisableTimeout is not supported. - * NotificationStoringWhenDisabledOrOffline is not supported. - ----- - - -### Awa client, server and bootstrap example. - -### Daemon setup. - -Example on how to interconnect all the daemons locally... - - -### Awa client tools examples. - - -### Awa server tools examples. - + * *LifeTime* specifies the minimum time (in seconds) that the server will wait after receiving a registration or update from the client before terminating that registration. + * *DefaultMinimumPeriod* specifies the default minimum period of observations. + * *DefaultMaximumPeriod* specifies the default maximum period of observations, -1 represents an indefinite period. + * *DisableTimeout* is not supported. + * *NotificationStoringWhenDisabledOrOffline* is not supported. ---- -## LWM2M Client Usage. - -### Connecting the Gateway client to the Gateway LWM2M server. - - $ build/core/src/bootstrap/awa_bootstrapd --verbose --port 15685 - $ build/core/src/server/awa_serverd --verbose - $ build/core/src/client/awa_clientd --endPointName client1 --bootstrap coap://127.0.0.1:15685 - -## Awa_API. - - The Awa API provides a method for applications to communicate with the LWM2M Client and Server daemons via the IPC interface. - The Client API header file can be found in "include/Awa/client.h". +## Using the LWM2M client. - The Server API header file can be found in "include/Awa/server.h". - Both server and client APIs are implemented within the libawa library. Applications can be linked against the either the static library "libawa.a" or shared library "libawa.so". - - The api/example directory contains a number of usage examples. - - The tools directory contains a number of useful tools. These are built with the daemons, by default. - -## Awa Client API tools. - - A number of command-line tools are provided for user interaction with the LWM2M daemon. These tools provide simple operations such as defining a custom object type, setting a resource value, retrieving a resource value, and waiting for a resource to change or be executed. They interact with the LWM2M daemon via the SDK and IPC channel, and are applications that interact with the daemon locally. - - Note that these are *not* LWM2M Protocol tools - they do not issue LWM2M operations. - -### Common Options. - - Each tool accepts the --help option to display all supported options. Common options include: - - -h, --help Print help and exit - -V, --version Print version and exit - -v, --verbose Increase program verbosity (shows more run-time information) - -d, --debug Increase program verbosity (shows a lot of run-time information) - -a, --ipcAddress=ADDRESS Connect to client daemon at address (default=`127.0.0.1') - -p, --ipcPort=PORT Connect to IPC port (default=`12345') - - --ipcAddress is used to specify the IP address of the client daemon to connect to. - - --ipcPort is used to specify the IPC port that the tool uses to communicate with the daemon. Both the daemon and the tool must use the same port. Changing the port allows users to run multiple instances of the client daemon on the same host. - - Most tools take one or more PATH parameters, specified in the format: - - /O - specifies the object ID for operations on entire object types. - /O/I - specifies the object ID and object instance ID for operations on specific object instances. - /O/I/R - specifies the object ID, object instance ID, and resource ID for operations on specific resources. - /O/I/R/i - specifies the object ID, object instance ID, resource ID and resource instance ID for operations on specific resource instances. - - For tools that write data, values can be specified with the format: - - PATH=VALUE - -## Defining a New Object definition. - - To create a custom object, the object definition must be registered with the daemon. The *add-definition* tool can be used to perform this operation. - - **NOTE: Any custom objects must be defined for both the Client and Server daemon - use the awa-server-add-definition tool to define a custom object with the server** - - First, the object itself is defined by providing an ID, descriptive name, mandatory or optional flag (to determine whether the device must provide at least one instance), and whether the object supports single or multiple instances. - - -o, --objectID=ID Object ID - -j, --objectName=NAME Object name - -m, --objectMandatory Object is required or optional (default=off) - -y, --objectInstances=TYPE Object supports single or multiple instances - (possible values="single", "multiple" - default=`single') - - Then each resource is specified by a sequence of resource options: - - -r, --resourceID=ID Resource ID - -n, --resourceName=NAME Resource Name - -t, --resourceType=TYPE Resource Type (possible values="opaque", - "integer", "float", "boolean", - "string", "time", "objectlink", - "none") - -u, --resourceInstances=VALUE Resource supports single or multiple instances - (possible values="single", "multiple") - -q, --resourceRequired=VALUE Resource is required or optional (possible - values="optional", "mandatory") - -k, --resourceOperations=VALUE - Resource Operation (possible values="r", - "w", "e", "rw", "rwe") +### Connecting the gateway client to the gateway LWM2M server. +```` +$ build/core/src/bootstrap/awa_bootstrapd --verbose --port 15685 +$ build/core/src/server/awa_serverd --verbose +$ build/core/src/client/awa_clientd --endPointName client1 --bootstrap coap://127.0.0.1:15685 +```` - For each --resourceID option, all other resource options must be specified. +### The Awa_API. - For example, to define TestObject2 as ObjectID 1000, with a single mandatory instance, and three resources: +The Awa API provides a way for applications to communicate with the LWM2M client and server daemons via the IPC interface. +The client API header file can be found in "include/Awa/client.h". +The server API header file can be found in "include/Awa/server.h". +Both server and client APIs are implemented in the *libawa* library. Applications may be linked against the either the static library *libawa.a* or the shared library *libawa.so*. - ./awa-client-define \ - --objectID=1000 --objectName=TestObject2 --objectMandatory --objectInstances=single \ - --resourceID=0 --resourceName=Resource0 --resourceType=string --resourceInstances=single --resourceRequired=mandatory --resourceOperations=rw \ - --resourceID=1 --resourceName=Resource1 --resourceType=integer --resourceInstances=single --resourceRequired=mandatory --resourceOperations=rw \ - --resourceID=2 --resourceName=Resource2 --resourceType=none --resourceInstances=single --resourceRequired=optiona --resourceOperations=e +Useful examples can be found in the *api/example* folder. The tools directory contains a number of useful tools. These are built with the daemons, by default. - Alternatively, an XML Definition file can be used to define a custom object - however this is not yet supported. +## Awa client API tools. -## Discovering a Device's Object and Resource Definitions. +Several command-line tools are available for user interaction with the LWM2M daemon. These tools support simple operations, such as defining a custom object type, setting a resource value, retrieving a resource value, and waiting for a resource to change or be executed. They interact with the LWM2M daemon via the SDK and IPC channel, and are applications that interact with the daemon locally. -You can discover the objects and resources that have been defined on the LWM2M server. The *awa-client-explore* tool can be used to perform this operation. The tool will list the objects and object-resources that are currently defined within the client daemon. +Note that these are *not* LWM2M Protocol tools - they do not issue LWM2M operations. -For example: +### Common options. - ./awa-client-explore +Common options include: -## Set a Resource Value. +| options | description | +|-----|-----| +| -h, --help | Print help and exit | +| -V, --version | Print version and exit | +| -v, --verbose | Increase program verbosity (shows more run-time information) | +| -d, --debug | Increase program verbosity (shows a lot of run-time information) | +| -a, --ipcAddress=ADDRESS | Connect to client daemon at address (default=`127.0.0.1') | +| -p, --ipcPort=PORT | Connect to IPC port (default=`12345') | - To set the value of a resource, the *awa-client-set* tool can be used. +*--ipcAddress* is used to specify the IP address of the client daemon to connect to. +*--ipcPort* is used to specify the IPC port that the tool uses to communicate with the daemon. Both the daemon and the tool must use the same port. Changing the port allows users to run multiple instances of the client daemon on the same host. - Mandatory resources should always exist provided the object instance exists. However before the value of any resource can be set, the object instance must first be created. And before an optional resource can be set, this resource must first be created. +Most tools take one or more PATH parameters, specified in the format: - For example, consider the case where object /1000 has been defined but no instances have been created. The following - command can be used to create instance 0 of object 1000: +| parameter | description | +|-----|-----| +| /O | specifies the object ID for operations on entire object types. | +| /O/I | specifies the object ID and object instance ID for operations on specific object instances. | +| /O/I/R | specifies the object ID, object instance ID, and resource ID for operations on specific resources. | +| /O/I/R/i | specifies the object ID, object instance ID, resource ID and resource instance ID for operations on specific resource instances. | - ./awa-client-set --create /1000/0 +For tools that write data, values can be specified with the format: ````PATH=VALUE```` - Any resources defined as optional must also be created before they can be set. +### Creating a new object definition. - For example: +An *object* is a collection of individual *resources* bundled together under a single identifier, along with some extra attributes that describe the nature of the object (listed below). Numerous standard objects are pre-defined within the LWM2M model but additional custom objects may also be defined as needed. Custom objects are created by registering the new object definition with the daemon. The *add-definition* tool is used to perform this operation. Note that an object definition does not result in an object instance. Creation of an object instance is a separate process. Resource manipulation is only possible on object instances. - ./awa-client-set --create /1000/0/0 +**NOTE: A custom object must be defined for both the client *and* server daemons. Use the *awa-server-add-definition* tool to define a custom object with the server.** - In the case where no value is specified the resource will be created and populated with the default values. +Firstly the object itself is defined by providing an ID, descriptive name, mandatory or optional flag (to determine whether the device must provide at least one instance), and whether the object supports single or multiple instances. - Once the resource has been created, the value of the resource can be set. +| object attribute | description | +|-----|-----| +| -o, --objectID=ID | Object ID | +| -j, --objectName=NAME | Object name | +| -m, --objectMandatory | Object is required or optional (default=off) | +| -y, --objectInstances=TYPE | Object supports single or multiple instances (possible values: *single* (default) or *multiple*) | - For example, to set the value of resource 0 (of type string), within object instance 0 of object 1000, to the value "Happy": +Secondly, each resource in the object is specified by a sequence of resource options: - ./awa-client-set /1000/0/0=Happy +| resource option | description | +|-----|-----| +| -r, --resourceID=ID | Resource ID | +| -n, --resourceName=NAME | Resource name | +| -t, --resourceType=TYPE | Resource type ( possible values: *opaque, integer, float, boolean, string, time, objectlink, none*) | +| -u, --resourceInstances=VALUE | Resource supports single or multiple instances (possible values: *single, multiple*) | +| -q, --resourceRequired=VALUE | Resource is required or optional (possible values: *optional, mandatory*) | +| -k, --resourceOperations=VALUE | Resource operation (possible values: *r, w, e, rw, rwe*) | - Note that it is not possible to set the value of a resource that is of type None. +**Note. For each *--resourceID* option, all other resource options must be specified.** - A specific resource instance of a multi-instance resource can be set with: +Example. Define TestObject2 as ObjectID 1000, with a single mandatory instance, and three resources: +```` +./awa-client-define \ + --objectID=1000 --objectName=TestObject2 --objectMandatory --objectInstances=single \ + --resourceID=0 --resourceName=Resource0 --resourceType=string --resourceInstances=single --resourceRequired=mandatory --resourceOperations=rw \ + --resourceID=1 --resourceName=Resource1 --resourceType=integer --resourceInstances=single --resourceRequired=mandatory --resourceOperations=rw \ + --resourceID=2 --resourceName=Resource2 --resourceType=none --resourceInstances=single --resourceRequired=optiona --resourceOperations=e +```` - ./awa-client-set /1000/0/1/7=Seventh +### Discovering a device's object and resource definitions. - Multiple set operations can be combined on the command line: +The *awa-client-explore* tool is used to discover the objects and resources that have been defined on the LWM2M server. The tool will also list the objects and object-resources that are currently defined within the client daemon. - ./awa-client-set --create /1000/0 /1000/0/0=Happy /1000/0/1/7=Seventh +Example: ````./awa-client-explore ```` -## Get a Resource Value. +### Setting resource values. - To retrieve the value of a resource and display it on the console, the *awa-client-get* tool can be used. +The *awa-client-set* tool can be used to set the value of a resource. - For example, to fetch and display the value of resource 0, within instance 0 of object 1000: +Mandatory resources always exist provided that the parent *object instance* exists, thus before the value of any resource can be set, the object instance must first be created. Before an *optional resource* can be set, this resource must first be created. - ./awa-client-get /1000/0/0 +Example. Consider the case where object /1000 has been defined but no instances have been created. The following can be used to create instance 0 of object 1000: ````./awa-client-set --create /1000/0 ```` - Multiple resources can be fetched: +Any mandatory resources associated with the object instance will also be instantiated with default values, but any resources defined as optional must be created explicitly before they can be set. - ./awa-client-get /1000/0/1 /1000/0/5 +For example, to create an instance of the optional resource 0 within instance 0 of object 1000: ````./awa-client-set --create /1000/0/0 ```` - Entire object instances can be fetched: +Because no value is specified for the new resource instance, it will be created and populated with its default value. - ./awa-client-get /1000/0 +Once the resource has been created, its value can be set. - All object instances for an object ID can be fetched: +For example, to set the value of resource 0 (which is of type string), within object instance 0 of object 1000, to the value *Happy*: - ./awa-client-get /1000 +````./awa-client-set /1000/0/0=Happy ```` - If the resource specified is a multiple-instance resource, all instances will be retrieved. Individual instances can be displayed by specifying the resource instance index: +**Note that it is not possible to set the value of a resource that is of type *None*.** - ./awa-client-get /1000/0/5/1 /1000/0/5/2 +A specific resource instance of a multi-instance resource can be set with: ````./awa-client-set /1000/0/1/7=Seventh ```` - The --quiet/-q option can be used to suppress the extra information displayed. +Multiple set operations can be combined on the command line: + + ````./awa-client-set --create /1000/0 /1000/0/0=Happy /1000/0/1/7=Seventh ```` -## Subscribe to a Change to a Resource. +### Retrieving a resource value. - It may be important for a script to block until the value of a resource changes, or an LWM2M Execute operation is performed on an resource that supports the execute operation. For this purpose, the *awa-client-subscribe* tool can be used. +The *awa-client-get* tool is used to retrieve the value of a client object resource and display it on the console. - This tool will display notifications whenever the target resource or object instance changes, or a target resource receives an Execute operation. When such a notification arrives, it will print details in the console. +For example, to retrieve and display the value of resource 0, within instance 0 of object 1000: ````./awa-client-get /1000/0/0 ```` - Note that this is **not** equivalent to a LWM2M Observe operation. This tool is observing the local resource hosted by the client daemon. +Multiple resources can be retrieved: ````./awa-client-get /1000/0/1 /1000/0/5 ```` - For example, to wait for a change to resource 200 within instance 0 of object 1000: +Entire object instances can be retrieved: ````./awa-client-get /1000/0 ```` - ./awa-client-subscribe /1000/0/200 +All object instances for an object ID can also be retrieved: ````./awa-client-get /1000 ```` - To wait for a change to any resource within instance 0 of object 1000: +If the resource specified is a multiple-instance resource, all instances will be retrieved. Individual instances can be displayed by specifying the resource instance index: ````./awa-client-get /1000/0/5/1 /1000/0/5/2 ```` - ./awa-client-subscribe /1000/0 +The *--quiet/-q* option can be used to suppress the display of any extra information. - Waiting for an LWM2M Execute operation is also possible, however a specific object instance and resource must be specified. For example, to wait on resource 4, which is an executable resource of instance 0 of object 3: +### Subscribing to a change of resource value. - ./awa-client-subscribe /3/0/4 +In some cases it may be important for a script to block until the value of a resource changes, or for an LWM2M resource execute operation to complete. The *awa-client-subscribe* tool can be used to act as a listener. - By default, *awa-client-subscribe* will wait indefinitely, displaying each notification as it arrives. With the time and count options, *awaclient-subscribe* can terminate after a number of notifications, or an elapsed period of time. +The *awa-client-subscribe* tool will display notifications whenever the value of the target resource or object instance changes, or when a target resource receives an execute operation. When a notification arrives, the details will be printed to the console. - -t, --waitTime=SECONDS Time to wait for notification (default=`0') - -c, --waitCount=NUMBER Number of notifications to wait for (default=`0') +Note that *awa-client-subscribe* is *not* the same a LWM2M *Observe* operation. This tool is listening to the local resource hosted by the client daemon. - For example, to wait for no longer than 60 seconds for a single notification: +For example, to listen for a change to resource 200 within instance 0 of object 1000: ````./awa-client-subscribe /1000/0/200 ```` - ./awa-client-subscribe /3/0/4 --waitTime=60 --waitCount=1 +To listen for a change to any resource within instance 0 of object 1000: ````./awa-client-subscribe /1000/0 ```` - Multiple paths can be combined on the command line: +Listening for an LWM2M Execute operation is also possible, however the target object instance and resource must be fully specified. For example, to wait on resource 4, which is an executable resource of instance 0 of object 3: ````./awa-client-subscribe /3/0/4 ```` - ./awa-client-subscribe /3/0/4 /3/0/5 /4 +By default, *awa-client-subscribe* will wait indefinitely, displaying each notification as it arrives. With the time and count options, *awa_client-subscribe* can terminate after a number of notifications, or an elapsed period of time. -## Delete a Resource. +| option | description | +|-----|-----| +| -t, --waitTime=SECONDS | Time to wait for notification (default=`0') | +| -c, --waitCount=NUMBER | Number of notifications to wait for (default=`0') | - To delete a resource from the client, the *awa-client-delete* tool can be used. - For example, to delete all object instances of object type 1000: +For example, to wait for no longer than 60 seconds for a single notification: ````./awa-client-subscribe /3/0/4 --waitTime=60 --waitCount=1 ```` - ./awa-client-delete /1000 +Multiple paths can be combined on the command line: ````./awa-client-subscribe /3/0/4 /3/0/5 /4 ```` - To delete the object instance of object type 1000 with ID 0: +### Deleting a resource. - ./awa-client-delete /1000/0 +To delete an object or resource instance from the client, use the *awa-client-delete* tool. +For example, to delete all object instances of object type 1000: ````./awa-client-delete /1000 ```` - To delete the resource with ID 5 from instance 0 of object ID 1000: +To delete the object instance of object type 1000 with ID 0: ````./awa-client-delete /1000/0 ```` - ./awa-client-delete /1000/0/5 +To delete the resource with ID 5 from instance 0 of object ID 1000: ````./awa-client-delete /1000/0/5 ```` - Unlike the *awa-server-delete* tool, this tool can modify the client's data structures directly, so is not limited by LWM2M Delete rules. +Unlike the *awa-server-delete* tool, this tool can modify the client's data structures directly, so is not limited by LWM2M Delete rules. -## Awa Server API Tools. +## Awa Server API tools. - Server tools are used to communicate with the LWM2M Server daemon and typically issue one or more LWM2M operations to a connected client. +Server tools are used to communicate with the LWM2M Server daemon and typically issue one or more LWM2M operations to a connected client. - Server tools often require a target client ID to be specified: +Server tools often require a target client ID to be specified: - -c, --clientID=ID ClientID +| option | description | +|-----|-----| +| -c, --clientID=ID | ClientID is the client endpoint name used by the client when registering with the LWM2M server. | - This ID is the client endpoint name used by the client when registering with the LWM2M server. -## List Registered Clients. +### Listing registered clients. The *awa-server-list-clients* tool can be used to list all clients currently registered with the LWM2M server daemon: - ./awa-server-list-clients - - The --clientID/-c option is not required. Each client endpoint name is displayed, one per line. - - If --verbose/-v is specified, the output shows the number of registered clients, and their client endpoint names: - - ./awa-server-list-clients --verbose - 2 Registered Clients: +````./awa-server-list-clients ```` - 1 imagination1 - 2 chris +The *--clientID/-c* option is not required. Each client endpoint name is displayed, one per line. - The option --objects/-o can be specified to retrieve and display the objects and object instances currently registered with the LWM2M server, for example: +If *--verbose/-v* is specified, the output shows the number of registered clients, and their client endpoint names: - ./awa-server-list-clients --objects - 1 imagination1 <2/0>,<4/0>,<7>,<3/0>,<5>,<6>,<0/1>,<1/1> - - The syntax is or . - - -## Define a New Object Definition. - - To use a custom object, the object definition must be registered with the server daemon. The *awa-server-define* tool can be used to perform this operation. +For eaxmple: ````./awa-server-list-clients --verbose ```` + +Returns: +```` +1 imagination1 +2 chris +```` - The *awa-server-define* tool has identical functionality to the *awa-client-define* tool, outlined in the section above. +The option *--objects/-o* can be specified to retrieve and display the objects and object instances currently registered with the LWM2M server in the format ```````` or ````````. -## Write a Resource Value on a Registered Client. +For example: ````./awa-server-list-clients --objects ```` +Returns +```` +1 imagination1 <2/0>,<4/0>,<7>,<3/0>,<5>,<6>,<0/1>,<1/1> +```` - To write the value of a resource on a registered client, the *awa-server-write* tool can be used. +### Creating a server object definition. - For example, to set the value of resource 0 (of type string) on the client "imagination1", within instance 0 of object 1000, to the value "Happy": +The *awa-server-define* tool is used to define custom objects on the server. To use a custom object, the object definition must be registered with the server daemon. The *awa-server-define* tool has identical functionality to *awa-client-define*, described earlier. - ./awa-server-write --clientID=imagination1 /1000/0/0=Happy +### Writing a value to a resource on a registered client. - Note that it is not possible to set the value of a resource that is of type None. +The *awa-server-write* tool is used to write the value of a resource on a registered client. - A multi-instance resource can be set by specifying the resource instances: +For example, to set the value of resource 0 (of type string) on the client "imagination1", within instance 0 of object 1000, to the value *Happy*: - ./awa-server-write --clientID=imagination1 /1000/0/5/1=123 /1000/0/5/2=456 +````./awa-server-write --clientID=imagination1 /1000/0/0=Happy ```` - To create a new instance of an object on a connected client, the --create option can be used. When an instance is created, any default values provided in the object definition are used. +Note that it is not possible to set the value of a resource that is of type *None*. - For example, to create instance 1 of object 1000 on the client "imagination1": +A multi-instance resource can be set by specifying the resource instances: - ./awa-server-write --clientID=imagination1 --create /1000/1 +````./awa-server-write --clientID=imagination1 /1000/0/5/1=123 /1000/0/5/2=456```` - To create a new instance with the next available object instance ID: +To create a new instance of an object on a connected client, the *--create* option can be used. +When an instance is created, any default values provided in the object definition are used. - ./awa-server-write --clientID=imagination1 --create /1000 +For example, to create instance 1 of object 1000 on the client *imagination1*: - The ID of the newly created object instance is displayed. +````./awa-server-write --clientID=imagination1 --create /1000/1 ```` - **Note: Create functionality is not yet supported** +To create a new instance with the next available object instance ID: -## Read a Resource Value from a Registered Client. +````./awa-server-write --clientID=imagination1 --create /1000 ```` - To retrieve the value of a resource and display it on the console, the *awa-server-read* tool can be used. +The ID of the newly created object instance is displayed. - For example, to display the value of resource 0, within instance 0 of object 1000: + **Note: Create functionality is not yet supported.** - ./awa-server-read --clientID=imagination1 /1000/0/0 +### Reading a resource value from a registered client. - Multiple resources and object instances can be read: +The *awa-server-read* tool is used to retrieve the value of a resource and display it on the console. For example, to display the value of resource 0, within instance 0 of object 1000: - ./awa-server-read -c imagination1 /1000/0/2 /1000/0/3 /1000/1 /1001 +````./awa-server-read --clientID=imagination1 /1000/0/0 ```` -## Delete an Object Instance from a Registered Client. +Multiple resources and object instances can be read using: - To delete an instance of an object from a connected client, the *awa-server-delete* tool can be used. +````./awa-server-read -c imagination1 /1000/0/2 /1000/0/3 /1000/1 /1001 ```` - For example, to delete object 1000, instance 0 from the client "imagination1": +### Deleting an object instance from a registered client. - ./awa-server-delete --clientID=imagination1 /1000/0 +The *awa-server-delete* tool is used to delete an instance of an object from a connected client. For example, to delete object 1000, instance 0 from the client "imagination1": - It is not possible to delete individual resources, resource instances, or entire objects due to LWM2M protocol restrictions. +````./awa-server-delete --clientID=imagination1 /1000/0 ```` -## Observe a Resource on a Registered Client. +**Note.** Due to LWM2M protocol restrictions it is not possible to delete individual resources, resource instances, or entire objects. - It may be important for a script to block until the value of a resource changes on a specific client. For this purpose, the *awa-server-observe* tool can be used. +### Observing a resource on a registered client. - This tool will display notifications whenever the target resource or object instance changes. When such a notification arrives, it will print details in the console. +In some cases a script may be required to block until the value of a resource changes on a specific client. For this purpose, the *awa-server-observe* tool is provided to display notifications whenever the target resource or object instance changes. - This is equivalent to a LWM2M Observe operation. This tool is observing the resources stored by a remote client. +When a notification arrives, the details will be printed to the console, which is the functional equivalent of a LWM2M *Observe* operation. - For example, to wait for a change to resource 200 within instance 0 of object 1000: +For example, to wait for a change to resource 200 within instance 0 of object 1000: - ./awa-server-observe --clientID imagination1 /1000/0/200 +````./awa-server-observe --clientID imagination1 /1000/0/200 ```` - To wait for a change to any resource within instance 0 of object 1000: +To wait for a change to any resource within instance 0 of object 1000: - ./awa-server-observe --clientID imagination1 /1000/0 +````./awa-server-observe --clientID imagination1 /1000/0 ```` - By default, *awa-server-observe* will wait indefinitely, displaying each notification as it arrives. With the time and count options, *awa-server-observe* can terminate after a number of notifications, or an elapsed period of time. +By default, *awa-server-observe* will wait indefinitely, displaying each notification as it arrives, but by using the time and count options, *awa-server-observe* can terminate after a number of notifications, or an elapsed period of time. - -t, --waitTime=SECONDS Time to wait for notification (default=`0') - -c, --waitCount=NUMBER Number of notifications to wait for (default=`0') +| option | description | +|-----|-----| +| -t, --waitTime=SECONDS | Time to wait for notification (default=`0') | +| -c, --waitCount=NUMBER | Number of notifications to wait for (default=`0') | - For example, to wait for no longer than 60 seconds for a single notification: +For example, to wait for no longer than 60 seconds for a single notification: - ./awa-server-observe --clientID imagination1 --waitTime=60 --waitCount=1 /1000/0/200 +````./awa-server-observe --clientID imagination1 --waitTime=60 --waitCount=1 /1000/0/200 ```` - Observe attributes that affect the way notifications are generated can be changed with the *awa-server-write-attributes* tool. +Observe attributes that affect the way notifications are generated can be changed with the *awa-server-write-attributes* tool. -## Execute a Resource on a Registered Client. +### Executing a resource on a registered client. - To initiate an Execute operation on a resource that supports the execute operation, the *awa-server-execute* tool can be used. +The *awa-server-execute* tool is used to initiate an *execute* operation on a resource that supports it. - For example, to initiate execution of object 1000, instance 0, resource 4 on the client "imagination1": +For example, to initiate execution of object 1000, instance 0, resource 4 on the client "imagination1": - ./awa-server-execute --clientID imagination1 /1000/0/4 +````./awa-server-execute --clientID imagination1 /1000/0/4 ```` - Multiple operations can be initiated with multiple paths: +Multiple operations can be initiated by applying multiple paths: - ./awa-server-execute --clientID imagination1 /1000/0/4 /1000/0/5 +````./awa-server-execute --clientID imagination1 /1000/0/4 /1000/0/5 ```` - Opaque data can be supplied as an argument to the execute operation by piping into the process via the --stdin option: +Opaque data can be supplied as an argument to the execute operation by piping into the process via the *--stdin* option: - ./awa-server-execute --stdin --clientID imagination1 /1000/0/4 < mydata +````./awa-server-execute --stdin --clientID imagination1 /1000/0/4 < mydata ```` - Note that data supplied is provided to all execute targets. +**Note that the data supplied will be piped to all of the stated execute targets.** - It is not possible to initiate an execute operation on an object, an object instance or a resource instance. +Execute operations on an object, an object instance or a resource instance are not possible. - It is not possible to initiate an execute operation on a resource that does not support the execute operation. +### Write attribute values of a resource or object instance on a registered client. -## Write Attributes of a Resource or Object Instance on a Registered Client. +The *awa-server-write-attributes* tool is used to change the value of attributes associated with a client's resource or object instance. - To change the value of attributes associated with a client's resource or object instance, the *awa-server-write-attributes* tool can be used. +For example, to set the *pmin* value of object 1000, instance 0, resource 4 on the client "imagination1" to 5 seconds: - For example, to set the pmin value of object 1000, instance 0, resource 4 on the client "imagination1" to 5 seconds: +````./awa-server-write_attributes --clientID imagination1 /1000/0/4\?pmin=5 ```` - ./awa-server-write_attributes --clientID imagination1 /1000/0/4\?pmin=5 +Multiple attribute values can be set with the same call. For example, to set the *pmin* attribute of object 1000, instance 0 on the client "imagination1" to 5 seconds, and *pmax* to 100 for the same object instance: - For example, to set the pmin attribute of object 1000, instance 0 on the client "imagination1" to 5 seconds, and pmax to 100 for the same object instance: +````./awa-server-write_attributes --clientID imagination1 /1000/0\?pmin=5\&pmax=100 ```` - ./awa-server-write_attributes --clientID imagination1 /1000/0\?pmin=5\&pmax=100 +Note that the *?* and *&* characters will need to be escaped for most shells. - Note that the ? and & characters need to be escaped for most shells. +---- +---- diff --git a/lib/jsmn/apply_patches b/lib/jsmn/apply_patches old mode 100755 new mode 100644 diff --git a/lib/libcoap/apply_patches b/lib/libcoap/apply_patches old mode 100755 new mode 100644 diff --git a/tools/tests/run_tests b/tools/tests/run_tests old mode 100755 new mode 100644