Merge pull request #18 from martinkosch/docstrings

Adding more docstrings, high level interface improvements

.gitignore

@@ -6,3 +6,4 @@
 gen/Manifest.toml
 gen/Manifest.toml
 .vscode/settings.json
+docs/Manifest.toml

Project.toml

@@ -17,6 +17,7 @@ Dates = "1.6"
 Distributed = "1.6"
 OffsetArrays = "1"
 Pkg = "1.6"
+Random = "1.6"
 SafeTestsets = "0.1.0"
 Test = "1.6"
 julia = "1.6"
@@ -27,8 +28,9 @@ Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
 Base64 = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
 Distributed = "8ba89e20-285c-5b6f-9357-94700520ee1b"
 Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 SafeTestsets = "1bc83da4-3b8d-516f-aca4-4fe02f6d838f"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Aqua", "Base64", "Distributed", "Pkg", "SafeTestsets", "Test"]
+test = ["Aqua", "Base64", "Distributed", "Pkg", "Random", "SafeTestsets", "Test"]

README.md

@@ -1,6 +1,103 @@
-# open62541
+# open62541.jl
 
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://martinkosch.github.io/open62541.jl/dev)
 [![CI](https://github.com/martinkosch/open62541.jl/actions/workflows/CI.yml/badge.svg)](https://github.com/martinkosch/open62541.jl/actions/workflows/CI.yml)
 [![codecov](https://codecov.io/gh/martinkosch/open62541.jl/graph/badge.svg?token=lJe2xOTO7g)](https://codecov.io/gh/martinkosch/open62541.jl)
 [![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
+
+open62541.jl is a [Julia](https://julialang.org) package that interfaces with the [open62541](https://www.open62541.org/)
+library written in C ([source](https://github.com/open62541/open62541)).
+
+As such, it provides functionality following the [OPC Unified Architecture (OPC UA) standard](https://en.wikipedia.org/wiki/OPC_Unified_Architecture)
+for data exchange from sensors to cloud applications developed by the [OPC Foundation](https://opcfoundation.org/).
+
+In short, it provides the ability to create OPC servers that make data from different
+sources available to clients and, naturally, also a client functionality that allows
+to read data from OPC UA servers. Features are summarized further on the [open62541 website](https://www.open62541.org/).
+
+open62541.jl's *ultimate* aim is to provide the full functionality of open62541 to
+Julia users through a convenient high level interface without the need to engage
+in manual memory management etc. (as required in open62541).
+
+At its current development stage the high level interface is implemented for a
+(commonly used) subset of functionality. An essentially feature-complete lower
+level interface that wraps all functionality of open62541 is, however, available.
+
+## Warning: active development
+
+Note that open62541.jl is still under active development and has not reached a maturity
+that would make it safe to use in a production environment.
+
+The developers aim to observe [semantic versioning](https://semver.org/), but
+accidental breakage and evolutions of the API have to be expected.
+
+Documentation is also a work in progress.
+
+## Installation
+
+open62541.jl is not yet registered in Julia's General registry, but it will
+hopefully be soon (status: May 2024).
+
+Assuming you have Julia already installed (otherwise: [JuliaLang Website](https://julialang.org/)),
+you can install by executing:
+
+```julia
+using Pkg
+Pkg.add("https://github.com/martinkosch/open62541.jl")
+```
+
+## Server example
+
+Starting up a server with a default configuration in open62541.jl is very simple.
+Just execute the following code in the REPL or as a script:
+
+```julia
+using open62541
+server = JUA_Server()
+config = JUA_ServerConfig(server)
+JUA_ServerConfig_setDefault(config)
+JUA_Server_runUntilInterrupt(server)
+```
+
+This will configure a server with the default configuration (address: opc.tcp://localhost:4840/)
+and start it. The server can be shut down by pressing CTRL+C multiple times.
+
+While the server is running, it can be accessed via the Client API of open62541.jl
+or it can be browsed and accessed with a graphical client, such as [UA Expert](https://www.unified-automation.com/products/development-tools/uaexpert.html).
+
+## Basic client example
+
+In order to showcase the Client API functionality, we will use the above server
+and read some basic information from it, namely the software version number and
+the current time. Note that this information should be contained in all OPC UA
+servers, so you could also connect to a different server that you know is running.
+
+```julia
+using open62541
+using Printf
+
+#initiate client, configure it and connect to server
+client = JUA_Client()
+config = JUA_ClientConfig(client)
+JUA_ClientConfig_setDefault(config)
+JUA_Client_connect(client, "opc.tcp://localhost:4840")
+
+#define nodeids that we are interested in 
+nodeid_currenttime = JUA_NodeId(0, UA_NS0ID_SERVER_SERVERSTATUS_CURRENTTIME)
+nodeid_version = JUA_NodeId(0, UA_NS0ID_SERVER_SERVERSTATUS_BUILDINFO_SOFTWAREVERSION)
+
+#read data from nodeids
+currenttime = JUA_Client_readValueAttribute(client, nodeid_currenttime) #Int64 which represents the number of 100 nanosecond intervals since January 1, 1601 (UTC)
+version = JUA_Client_readValueAttribute(client, nodeid_version) #String containing open62541 version number
+
+#Convert current time into human understandable format
+dts = UA_DateTime_toStruct(currenttime)
+
+#Print results to terminal
+Printf.@printf("current date and time (UTC) is: %u-%u-%u %u:%u:%u.%03u\n",
+    dts.day, dts.month, dts.year, dts.hour, dts.min, dts.sec, dts.milliSec)
+Printf.@printf("The server is running open62541 version %s.", version)
+
+#disconnect the client (good housekeeping practice)
+JUA_Client_disconnect(client)
+```

docs/make.jl

@@ -12,27 +12,38 @@ makedocs(;
         prettyurls = get(ENV, "CI", "false") == "true",
         canonical = "https://martinkosch.github.io/open62541.jl",
         assets = String[],
-        size_threshold=8000 * 2^10,
-        repolink = "https://github.com/martinkosch/open62541.jl",
+        size_threshold = 8000 * 2^10,
+        repolink = "https://github.com/martinkosch/open62541.jl"
     ),
     pages = [
-        "Home" => "index.md"
+        "Home" => "index.md",
+        "Manual" => [
+            "manual/numbertypes.md",
+            "manual/nodeid.md",
+            "manual/attributegeneration.md",
+            "manual/server.md",
+            "manual/client.md"
+        ],
+        "Tutorials" => [
+            "tutorials/server_first_steps.md",
+            "tutorials/client_first_steps.md"
+        ]
     ],
     warnonly = Documenter.except(
-        :autodocs_block, 
+        :autodocs_block,
         # :cross_references, 
-        :docs_block, 
-        :doctest, 
-        :eval_block, 
-        :example_block, 
-        :footnote, 
-        :linkcheck_remotes, 
-        :linkcheck, 
-        :meta_block, 
-        :missing_docs, 
-        :parse_error, 
+        :docs_block,
+        :doctest,
+        :eval_block,
+        :example_block,
+        :footnote,
+        :linkcheck_remotes,
+        :linkcheck,
+        :meta_block,
+        #:missing_docs, 
+        :parse_error,
         :setup_block
-    ),
+    )
 )
 
 deploydocs(;

docs/src/index.md

@@ -2,13 +2,13 @@
 CurrentModule = open62541
 ```
 
-# open62541
+# open62541.jl
 
 Documentation for [open62541](https://github.com/martinkosch/open62541.jl).
 
 ```@index
 ```
 
-```@autodocs
+<!-- ```@autodocs
 Modules = [open62541]
-```
+``` -->

docs/src/manual/attributegeneration.md

@@ -0,0 +1,40 @@
+# Attribute generation
+
+This page lists docstrings of functions used for the convenient generation of 
+node attribute structures. Their main use is when adding nodes to a server through 
+client API (see [`JUA_Client_addNode`](@ref)) or the server API (see [`JUA_Server_addNode`](@ref)).
+
+Convenience functions that allow setting values for specific attributes:
+
+```@docs
+UA_VALUERANK
+UA_ACCESSLEVEL
+UA_USERACCESSLEVEL
+UA_WRITEMASK
+UA_USERWRITEMASK
+UA_EVENTNOTIFIER
+```
+
+High level generators for attribute blocks:
+```@docs
+JUA_VariableAttributes
+JUA_VariableTypeAttributes
+JUA_ObjectAttributes
+JUA_ObjectTypeAttributes
+JUA_MethodAttributes
+JUA_ViewAttributes
+JUA_DataTypeAttributes
+JUA_ReferenceTypeAttributes
+```
+
+Lower level generators for attribute blocks:
+```@docs
+UA_VariableAttributes_generate
+UA_VariableTypeAttributes_generate
+UA_ObjectAttributes_generate
+UA_ObjectTypeAttributes_generate
+UA_MethodAttributes_generate
+UA_ViewAttributes_generate
+UA_DataTypeAttributes_generate
+UA_ReferenceTypeAttributes_generate
+```

docs/src/manual/client.md

@@ -0,0 +1,68 @@
+# Client
+
+This page lists docstrings relevant to the client API.
+
+## Adding different types of nodes:
+
+```@docs
+JUA_Client_addNode
+UA_Client_addVariableNode
+UA_Client_addObjectNode 
+UA_Client_addVariableTypeNode
+UA_Client_addObjectTypeNode
+UA_Client_addViewNode
+UA_Client_addReferenceTypeNode
+UA_Client_addDataTypeNode
+```
+
+## Reading from nodes:
+
+```@docs
+UA_Client_readAccessLevelAttribute
+UA_Client_readBrowseNameAttribute
+UA_Client_readContainsNoLoopsAttribute
+UA_Client_readDataTypeAttribute
+UA_Client_readDescriptionAttribute
+UA_Client_readDisplayNameAttribute
+UA_Client_readEventNotifierAttribute
+UA_Client_readExecutableAttribute
+UA_Client_readHistorizingAttribute
+UA_Client_readInverseNameAttribute
+UA_Client_readIsAbstractAttribute
+UA_Client_readMinimumSamplingIntervalAttribute
+UA_Client_readNodeClassAttribute
+UA_Client_readNodeIdAttribute
+UA_Client_readSymmetricAttribute
+UA_Client_readUserAccessLevelAttribute
+UA_Client_readUserExecutableAttribute
+UA_Client_readUserWriteMaskAttribute
+UA_Client_readValueAttribute
+UA_Client_readValueRankAttribute
+UA_Client_readWriteMaskAttribute
+```
+
+## Writing to nodes:
+
+```@docs
+UA_Client_writeAccessLevelAttribute
+UA_Client_writeBrowseNameAttribute
+UA_Client_writeContainsNoLoopsAttribute
+UA_Client_writeDataTypeAttribute
+UA_Client_writeDescriptionAttribute
+UA_Client_writeDisplayNameAttribute
+UA_Client_writeEventNotifierAttribute
+UA_Client_writeExecutableAttribute
+UA_Client_writeHistorizingAttribute
+UA_Client_writeInverseNameAttribute
+UA_Client_writeIsAbstractAttribute
+UA_Client_writeMinimumSamplingIntervalAttribute
+UA_Client_writeNodeClassAttribute
+UA_Client_writeNodeIdAttribute
+UA_Client_writeSymmetricAttribute
+UA_Client_writeUserAccessLevelAttribute
+UA_Client_writeUserExecutableAttribute
+UA_Client_writeUserWriteMaskAttribute
+UA_Client_writeValueAttribute
+UA_Client_writeValueRankAttribute
+UA_Client_writeWriteMaskAttribute
+```

docs/src/manual/nodeid.md

@@ -0,0 +1,22 @@
+# Nodeid
+
+This page lists docstrings of functions used to create NodeId identifiers.
+
+## Low level interface
+
+test
+
+```@docs
+UA_NODEID
+UA_NODEID_BYTESTRING_ALLOC
+UA_NODEID_GUID
+UA_NODEID_NUMERIC
+UA_NODEID_STRING
+UA_NODEID_STRING_ALLOC
+```
+
+## High level interface
+
+```@docs
+JUA_NodeId
+```

docs/src/manual/numbertypes.md

@@ -0,0 +1,14 @@
+# Supported number types
+
+It is noteworthy that the open62541 library supports the following Julia
+number types natively. open62541.jl provides support for the same number types.
+Adding other types is possible, but must rely on a custom datatype. See the [open62541 documentation](https://github.com/open62541/open62541/tree/master/examples/custom_datatype).
+
+**Real:**
+
+  - Integers: Int8, Int16, Int32, Int64, UInt8, UInt16, UInt32, UInt64.
+  - Float: Float32 and Float64.
+
+**Complex:**
+
+  - Complex{Float32}, Complex{Float64}