//
//  Licensed to the Apache Software Foundation (ASF) under one or more
//  contributor license agreements.  See the NOTICE file distributed with
//  this work for additional information regarding copyright ownership.
//  The ASF licenses this file to You under the Apache License, Version 2.0
//  (the "License"); you may not use this file except in compliance with
//  the License.  You may obtain a copy of the License at
//
//      https://www.apache.org/licenses/LICENSE-2.0
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
//
:imagesdir: ../../images/users/protocols
:icons: font

= UMAS (Schneider Electric PLCs)

This protocol is used by Schneider Electric PLCs such as the M340, M580 and the Quantum PLCs with the Unity firmware.

This driver supports reading/writing/browsing of PLC tags as well as %S/%SW addresses.

The Data Dictionary needs to be enabled on the PLC.

(Supported by Plc4Py Only)

== Connection String Options

[cols="2,2a,2a,2a,4a"]
|===
|Name |Type |Default Value |Required |Description
|Name 4+|UMAS
|Code 4+|`umas`
|Default Transport 4+|`tcp`
|Supported Transports 4+|
 - `tcp`
5+|Config options:
|`request-timeout` |INT |5000| |Default timeout for all types of requests.
|`unit-identifier` |INT |1| |Unit-identifier or slave-id that identifies the target PLC. Defaults to 1.
+++

|===
== Supported Operations

[cols="2,2a,5a"]
|===
|Name |Value |Description

3+|Supported Operations

|
2+| `read`

|
2+| `write`

|
2+| `browse`
|===

== Individual Resource Address Format

=== Connection String

UMAS has the following connection string format:-
----
umas:{transport}://{ip-address}:{port}?{options}
----
An example connection string would look like:-
----
umas:tcp://127.0.0.1:502
----
Note the transport, port and option fields are optional.


=== General Format

In general all UMAS addresses have this format:

----
{tag-name}.{child-name}.{child-name}:{data-type}[{array-size}]
----

Depending on the type of tag the child-name parameters are optional.
e.g. A tag with a BOOL data type could be 'TESTING_BOOL_1' whereas
if it is a UDT the tag name is followed by the child 'TESTING_UDT_1.START' which in itself could be a BOOL.

If the array-size part is omitted, the size-default of `1` is assumed.

If the data-type part is omitted, it defaults to the data type of the tag read from the PLC.

=== Memory Areas

Apart from tags defined in the PLC the driver is also able to access the %S and %SW
system memory areas.

The specific address details of the data in these areas are outlined in the devices
manual.

An example of the address format of these areas is %SW1 or %S20.

=== Data Types

The following data types are supported

- BOOL (boolean)
- SINT (int 8)
- USINT (uint 8)
- BYTE (uint 8)
- INT (int 16)
- UINT (uint 16)
- WORD (uint 16)
- DINT (int 32)
- UDINT (uint 32)
- DWORD (uint 32)
- REAL (float)
- STRING (char)
- TIME
- DATE
- TOD (Time of Day)
- DATE_AND_TIME
