Documentation changes

docs/compatibility.md

@@ -177,13 +177,13 @@ The `tools/certificate-creator` tool will create a demo public self-signed cert
 It can be built from source, or the crate:
 
 ```bash
-cargo install --force opcua-certificate-creator
+$ cargo install --force opcua-certificate-creator
 ```
 
 A minimal usage might be something like this inside samples/simple-client and/or samples/simple-server:
 
 ```bash
- opcua-certificate-creator --pkipath ./pki
+$ opcua-certificate-creator --pkipath ./pki
 ```
 
 A full list of arguments can be obtained by ```--help``` and you are advised to set fields such

docs/cross-compile.md

@@ -1,17 +1,33 @@
 # Cross-compiling OPC UA for Rust
 
+The Raspberry Pi will be used as the target device for this document. If you have
+another target, e.g. some `bitbake` concoction, then you will have to adapt the instructions
+accordingly.
+
 Cross compilation is described in two ways - one that uses the `cross` tool and one that is manual. Depending on your needs you may decide on one
- or the other. Both require Linux or Windows Subsystem for Linux in Windows 10.
+ or the other. 
+
+## Build with Cross
+
+The `cross` tool attempts to make it as simple as possible to cross-compile software by automatically fetching the appropriate cross compile toolchain and environment.
+
+Install [docker](https://www.docker.com/) if you have not already.
+
+```
+$ sudo apt install docker.io
+```
+
+Install [cross](https://github.com/rust-embedded/cross) for Rust.
 
-## The automatic way
+```
+$ cargo install cross
+```
 
-Install [cross](https://github.com/rust-embedded/cross) for Rust. Install the tool according its own instructions. Ensure your
- docker permissions are set. Now you can use `cross` in place of `cargo`.
-
-e.g.
+Install the tool according its own instructions. Ensure your docker permissions are 
+set. Now you can use `cross` in place of `cargo`. e.g.
 
 ```
-cross build --all --target armv7-unknown-linux-gnueabihf
+$ cross build --all --target armv7-unknown-linux-gnueabihf
 ```
 
 The additional argument `--target armv7-unknown-linux-gnueabihf` tells `cross` to set up a build environment
@@ -20,9 +36,9 @@ The additional argument `--target armv7-unknown-linux-gnueabihf` tells `cross` t
 ### SELinux conflict
 
 The `cross` tool may have an [issue](https://github.com/rust-embedded/cross/issues/112) running `cargo` on
- Fedora / Red Hat dists due SELinux policy. Read the bug for a workaround.
+ Fedora / Red Hat dists due to a SELinux policy. Read the bug for a workaround.
 
-## The manual way
+## Manual build
 
 The manual process gives you complete control on the build process but requires a bit more work.
 
@@ -47,29 +63,29 @@ These steps are derived from from sodiumoxide [readme](https://github.com/sodium
 Debian has convenient packages for cross compilation and emulation.
 
 ```
-sudo apt update
-sudo apt install build-essential gcc-arm-linux-gnueabihf libc6-armhf-cross libc6-dev-armhf-cross qemu-system-arm qemu-user-static -y
+$ sudo apt update
+$ sudo apt install build-essential gcc-arm-linux-gnueabihf libc6-armhf-cross libc6-dev-armhf-cross qemu-system-arm qemu-user-static -y
 ```
 
 ### Download and build OpenSSL
 
-Derived from stackoverflow [answer](https://stackoverflow.com/questions/37375712/cross-compile-rust-openssl-for-raspberry-pi-2) and adapted to opcua:
+Derived from a Stack Overflow [answer](https://stackoverflow.com/questions/37375712/cross-compile-rust-openssl-for-raspberry-pi-2) and adapted to opcua:
 
 ```
-cd /tmp
+$ cd /tmp
 
-wget https://www.openssl.org/source/openssl-1.0.1t.tar.gz
-tar xzf openssl-1.0.1t.tar.gz
+$ wget https://www.openssl.org/source/openssl-1.0.1t.tar.gz
+$ tar xzf openssl-1.0.1t.tar.gz
 
-cat > .opcuaARMenv << EOF
+$ cat > .opcuaARMenv << EOF
 export MACHINE=armv7
 export ARCH=arm
 export CC=arm-linux-gnueabihf-gcc
 EOF
 
-source .opcuaARMenv
+$ source .opcuaARMenv
 
-cd openssl-1.0.1t && ./config shared && make && cd -
+$ cd openssl-1.0.1t && ./config shared && make && cd -
 ```
 
 ### Build OPC UA for Rust
@@ -79,17 +95,17 @@ cd openssl-1.0.1t && ./config shared && make && cd -
 The `rustup` tool allows us to add another target to the Rust toolchain.
 
 ```
-rustup target add armv7-unknown-linux-gnueabihf
+$ rustup target add armv7-unknown-linux-gnueabihf
 ```
 
 #### Add target to OPC UA for Rust
 
 With the compiler ready, we move onto the project and set up the target.
 
 ```
-cd /my/path/to/opcua
-mkdir .cargo
-cat > .cargo/config << EOF
+$ cd /my/path/to/opcua
+$ mkdir .cargo
+$ cat > .cargo/config << EOF
 [target.armv7-unknown-linux-gnueabihf]
 linker = "arm-linux-gnueabihf-gcc"
 EOF
@@ -108,7 +124,7 @@ Building is straightforward and just requires we specify where OpenSSL was built
 correct build target.
 
 ```
-cat > .opcuaSSLenv << EOF
+$ cat > .opcuaSSLenv << EOF
 export OPENSSL_LIB_DIR=/tmp/openssl-1.0.1t/
 export OPENSSL_INCLUDE_DIR=/tmp/openssl-1.0.1t/include
 export OPENSSL_STATIC=1
@@ -129,15 +145,15 @@ Qemu can run Arm binaries from your host environment with a `qemu-arm-static` co
 So now we can test if the build works:
 
 ```
-source .opcuaSSLenv
-cd samples/simple-client
-qemu-arm-static ../../target/armv7-unknown-linux-gnueabihf/debug/opcua-simple-client
+$ source .opcuaSSLenv
+$ cd samples/simple-client
+$ qemu-arm-static ../../target/armv7-unknown-linux-gnueabihf/debug/opcua-simple-client
 ```
 
 or
 
 ```
-source .opcuaSSLenv
-cd samples/demo-server
-qemu-arm-static ../../target/armv7-unknown-linux-gnueabihf/debug/opcua-demo-server
+$ source .opcuaSSLenv
+$ cd samples/demo-server
+$ qemu-arm-static ../../target/armv7-unknown-linux-gnueabihf/debug/opcua-demo-server
 ```

docs/setup.md

@@ -84,13 +84,13 @@ OPC UA for Rust follows the normal Rust conventions. There is a `Cargo.toml` per
 and all dependencies. e.g.
 
 ```bash
-cd opcua/samples/demo-server
-cargo build
+$ cd opcua/samples/demo-server
+$ cargo build
 ```
 
 There is also a workspace `Cargo.toml` from the root directory. You may also build the entire workspace like so:
 
 ```bash
-cd opcua
-cargo build
+$ cd opcua
+$ cargo build
 ```

docs/testing.md

@@ -7,21 +7,25 @@ Unit tests should cover at least the following
 * Size limits validation on string, array fields in encoded messages
 * OpenSecureChannel, CloseSecureChannel request and response
 * Every service set call
-* Sign, verify, encrypt and decrypt (when implemented)
+* Sign, verify, encrypt and decrypt
 * Data change filters
+* Event filters
 * Subscription state engine
+* Bug fixes
 
 ## Integration testing
 
-Integration testing shall wait for client and server implementations to be functional. At that point it should be 
-possible to write a unit test that initiates a connection from a client to a server and 
-simulates scenarios such as.
+Integration tests will run a server listening on a port and a client connecting to it via
+ a socket to perform tests such as: 
 
 * Discovery service
 * Connect / disconnect
-* Create session
+* Create / Activate session
 * Subscribe to values
-* Encryption
+* Encrypted communication with each security profile
+* Permission based actions, e.g. read node values without session
+
+The integration tests are slower than unit tests and cannot run concurrently so they are run manually.
 
 ## Benchmarks
 
@@ -35,8 +39,8 @@ At present there is only benchmark for:
 Invoking benchmarks:
 
 ```
-cd opcua/server
-cargo bench
+$ cd opcua/server
+$ cargo bench
 ```
 
 The Criterion tool runs tests and requires `gnuplot` to generate reports of performance over time.