Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

#

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Fixed some typos and grammatical errors in the README. #1306

Merged
merged 1 commit into from
May 11, 2023
Merged

Fixed some typos and grammatical errors in the README. #1306

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
156 changes: 78 additions & 78 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,23 +8,22 @@ http://freeopcua.github.io/, https://github.com/FreeOpcUa/opcua-asyncio
# opcua-asyncio

opcua-asyncio is an asyncio-based asynchronous OPC UA client and server based on python-opcua, removing support of python < 3.7.
Asynchronous programming allows for simpler code (e.g. less need for locks) and potentially performance gains.
This library has also [sync wrapper](https://github.com/FreeOpcUa/opcua-asyncio/blob/master/asyncua/sync.py) over async API which may can be used in sync code instead of python-opcua
Asynchronous programming allows for simpler code (e.g. less need for locks) and can potentially provide performance improvements.
This library also provides a [synchronous wrapper](https://github.com/FreeOpcUa/opcua-asyncio/blob/master/asyncua/sync.py) over the async API, which can be used in synchronous code instead of python-opcua.

---

OPC UA binary protocol implementation has been tested against many different OPC UA stacks. API offers both a low level interface to send and receive all UA defined structures and high level classes allowing to write a server or a client in a few lines. It is easy to mix high level objects and low level UA calls in one application. Most low level code is autogenerated from xml specification.

coverage.py reports a test coverage of over 95 % of code, most of non-tested code is autogenerated code that is not used yet.
The OPC UA binary protocol implementation has undergone extensive testing with various OPC UA stacks. The API offers both a low level interface to send and receive all UA defined structures and high level classes allowing to write a server or a client in a few lines. It is easy to mix high level objects and low level UA calls in one application. Most low level code is autogenerated from xml specification.

The test coverage reported by coverage.py is over 95%, with the majority of the non-tested code being autogenerated code that is not currently in use.

# Warnings

opcua-asyncio is open-source and comes with absolutely no warranty. We try to keep it as much bug-free as possible and try to keep API stable but bugs and API changes will happen! Especially API changes will happen before any 1.0 release.
opcua-asyncio is open-source and comes with absolutely no warranty. We try to keep it as bug-free as possible, and try to keep the API stable, but bugs and API changes will happen! In particular, API changes are expected to take place prior to any 1.0 release.

Some renaming of methods from get_xx to read_xx and set_xx to write_xxx have been made to better follow OPC UA naming conventions

Version 0.9.9 introduces some argument renaming due to more automatic code generation. Especially the arguments to NodeId, BrowseName, LocalizedText and DataValue are now CamelCase instead of lower case, thus follow the OPC Ua convention used in all other structures in this library
Version 0.9.9 introduces some argument renaming due to more automatic code generation. Especially the arguments to NodeId, BrowseName, LocalizedText and DataValue, which are now CamelCase instead of lower case, following the OPC UA conventions used in all other structures in this library

# Installation

Expand All @@ -38,11 +37,10 @@ We assume that you already have some experience with Python, the asyncio module,

## Client class

The `Client` class provides a high level API for connecting to APU UA servers, session management and access to basic
The `Client` class provides a high level API for connecting to OPC UA servers, session management and access to basic
address space services.
The client can be used as a context manager. The client will then automatically connect and disconnect withing the `with`syntax.


```python
from asyncua import Client

Expand Down Expand Up @@ -73,93 +71,92 @@ The `Server` class provides a high level API for creation of OPC UA server insta

The documentation is available here [ReadTheDocs](http://opcua-asyncio.readthedocs.org/en/latest/).

The API remains mostly unchanged in regards to [python-opcua](http://opcua-asyncio.rtfd.io/).
Main difference is that most methods are now async.
The API remains mostly unchanged with regards to [python-opcua](http://opcua-asyncio.rtfd.io/).
The main difference is that most methods are now asynchronous.
Please have a look at [the examples](https://github.com/FreeOpcUa/opcua-asyncio/blob/master/examples) and/or the code.

A simple GUI client is available: https://github.com/FreeOpcUa/opcua-client-gui
A simple GUI client is available at: https://github.com/FreeOpcUa/opcua-client-gui

Browse the examples: https://github.com/FreeOpcUa/opcua-asyncio/tree/master/examples

A good starting point are the minimal examples.
The minimal examples are a good starting point.
Minimal client example: https://github.com/FreeOpcUa/opcua-asyncio/blob/master/examples/client-minimal.py
Minimal server example: https://github.com/FreeOpcUa/opcua-asyncio/blob/master/examples/server-minimal.py

A set of command line tools also available: https://github.com/FreeOpcUa/opcua-asyncio/tree/master/tools
* `uadiscover `(find_servers, get_endpoints and find_servers_on_network calls)
* `uals `(list children of a node)
* `uahistoryread`
* `uaread `(read attribute of a node)
* `uawrite `(write attribute of a node)
* `uacall `(call method of a node)
* `uasubscribe `(subscribe to a node and print datachange events)
* `uaclient `(connect to server and start python shell)
* `uaserver `(starts a demo OPC UA server)
`tools/uaserver --populate --certificate cert.pem --private_key pk.pem`

- `uadiscover `(find_servers, get_endpoints and find_servers_on_network calls)
- `uals `(list children of a node)
- `uahistoryread`
- `uaread `(read attribute of a node)
- `uawrite `(write attribute of a node)
- `uacall `(call method of a node)
- `uasubscribe `(subscribe to a node and print datachange events)
- `uaclient `(connect to server and start python shell)
- `uaserver `(starts a demo OPC UA server)
`tools/uaserver --populate --certificate cert.pem --private_key pk.pem`

How to generate certificate: https://github.com/FreeOpcUa/opcua-asyncio/tree/master/examples/generate_certificate.sh

## Client support

What works:

* connection to server, opening channel, session
* browsing and reading attributes value
* getting nodes by path and nodeids
* creating subscriptions
* subscribing to items for data change
* subscribing to events
* adding nodes
* method call
* user and password
* history read
* login with certificate
* communication encryption
* removing nodes
- connection to server, opening channel, session
- browsing and reading attributes value
- getting nodes by path and nodeids
- creating subscriptions
- subscribing to items for data change
- subscribing to events
- adding nodes
- method call
- user and password
- history read
- login with certificate
- communication encryption
- removing nodes

Tested servers: freeopcua C++, freeopcua Python, prosys, kepware, beckhoff, winCC, B&R, …

Not implemented yet:

* localized text feature
* XML protocol
* UDP (PubSub stuff)
* WebSocket
* maybe automatic reconnection...

- localized text feature
- XML protocol
- UDP (PubSub stuff)
- WebSocket
- maybe automatic reconnection...

## Server support

What works:

* creating channel and sessions
* read/set attributes and browse
* getting nodes by path and nodeids
* autogenerate address space from spec
* adding nodes to address space
* datachange events
* events
* methods
* basic user implementation (one existing user called admin, which can be disabled, all others are read only)
* encryption
* certificate handling
* removing nodes
* history support for data change and events
* more high level solution to create custom structures
- creating channel and sessions
- read/set attributes and browse
- getting nodes by path and nodeids
- autogenerate address space from spec
- adding nodes to address space
- datachange events
- events
- methods
- basic user implementation (one existing user called admin, which can be disabled, all others are read only)
- encryption
- certificate handling
- removing nodes
- history support for data change and events
- more high level solution to create custom structures

Tested clients: freeopcua C++, freeopcua Python, uaexpert, prosys, quickopc

Not yet implemented:

* UDP (PubSub stuff)
* WebSocket
* session restore
* alarms
* XML protocol
* views
* localized text features
* better security model with users and password

- UDP (PubSub stuff)
- WebSocket
- session restore
- alarms
- XML protocol
- views
- localized text features
- better security model with users and password

### Running a server on a Raspberry Pi

Expand All @@ -168,26 +165,25 @@ long startup times on less powerful devices like a Raspberry Pi. By passing a pa
a shelve holding the address space will be created during the first startup. All following startups will make use of the
cache-file which leads to significantly better startup performance (~3.5 vs 125 seconds on a Raspberry Pi Model B).


# Development

Code follows PEP8 apart for line lengths which should be max 160 characters and OPC UA structures that keep camel case
from XML definition.

All protocol code is under opcua directory

- `asyncua/ua` contains all UA structures from specification, most are autogenerated
- `asyncua/common` contains high level objects and methods used both in server and client
- `asyncua/client` contains client specific code
- `asyncua/server` contains server specific code
- `asyncua/utils` contains some utilities function and classes
- `asyncua/tools` contains code for command lines tools
- `schemas` contains the XML and text files from specification and the python scripts used to autogenerate code
- `tests` contains tests
- `docs` contains files to auto generate documentation from doc strings
- `examples` contains many example files
- `examples/sync` contains many example files using sync API
- `tools` contains python scripts that can be used to run command line tools from repository without installing
- `asyncua/ua` contains all UA structures from specification, most are autogenerated
- `asyncua/common` contains high level objects and methods used both in server and client
- `asyncua/client` contains client specific code
- `asyncua/server` contains server specific code
- `asyncua/utils` contains some utilities function and classes
- `asyncua/tools` contains code for command lines tools
- `schemas` contains the XML and text files from specification and the python scripts used to autogenerate code
- `tests` contains tests
- `docs` contains files to auto generate documentation from doc strings
- `examples` contains many example files
- `examples/sync` contains many example files using sync API
- `tools` contains python scripts that can be used to run command line tools from repository without installing

## Running tests:

Expand All @@ -196,7 +192,9 @@ python -m pip install -r requirements.txt
python -m pip install -r dev_requirements.txt
pytest -v -s
```

Or

```
./run-test.sh -v -s
```
Expand All @@ -206,7 +204,9 @@ Or
```
pytest -v -s --cov asyncua --cov-report=html
```

Or

```
./run-test.sh -v -s --cov asyncua --cov-report=html
```