Skip to content
New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

docs(snap): Move usage instructions to docs #342

Merged
merged 3 commits into from
May 6, 2022
Merged

docs(snap): Move usage instructions to docs #342

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
42c044e
docs(snap): Add packaging section
MonicaisHer May 5, 2022
ee4f2ed
docs(snap): Remove usage instructions from readme
MonicaisHer May 5, 2022
1f3c8e5
docs: cleanup references
MonicaisHer May 5, 2022
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
15 changes: 8 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,13 @@ $ ./simulator
Modbus TCP address: 0.0.0.0:1502
Start up a Modbus TCP simulator.
```
### Running the device-modbus Service as a Snap
EdgeX Device modbus is also available as a snap package. Install the snap with the following command:
```
sudo snap install edgex-device-modbus
```
For more details on the Device modbus Snap, including installation, configuration, please refer to [EdgeX Modbus Device Service Snap](https://github.com/edgexfoundry/device-modbus-go/tree/main/snap)
## Packaging

This component is packaged as docker image and snap.

For more details on deploying EdgeX with Snaps, viewing logs, security services, please check [Getting Started with Snap](https://docs.edgexfoundry.org/2.0/getting-started/Ch-GettingStartedSnapUsers/)
For docker, please refer to the [Dockerfile](Dockerfile) and [Docker Compose Builder] scripts.

For the snap, refer to the [snap](snap) directory.

## Modbus RTU Usage
Users can refer to [the document](https://docs.edgexfoundry.org/2.0/examples/Ch-ExamplesAddingModbusDevice/#set-up-the-modbus-rtu-device) to set up the Modbus RTU device.
Expand All @@ -38,3 +37,5 @@ Users can refer to [the document](https://docs.edgexfoundry.org/2.0/examples/Ch-

## License
[Apache-2.0](LICENSE)

[Docker Compose Builder]: https://github.com/edgexfoundry/edgex-compose/tree/main/compose-builder
170 changes: 19 additions & 151 deletions snap/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,170 +1,38 @@
# EdgeX Modbus Device Service Snap
[![snap store badge](https://raw.githubusercontent.com/snapcore/snap-store-badges/master/EN/%5BEN%5D-snap-store-black-uneditable.png)](https://snapcraft.io/edgex-device-modbus)
[![edgex-device-modbus](https://snapcraft.io/edgex-device-modbus/badge.svg)](https://snapcraft.io/edgex-device-modbus)

This folder contains snap packaging for the EdgeX Modbus Device Service Snap
This directory contains the snap packaging of the EdgeX Modbus device service.

The snap currently supports both `amd64` and `arm64` platforms.
The snap is built automatically and published on the Snap Store as [edgex-device-modbus].

## Installation
For usage instructions, please refer to Device Modbus section in [Getting Started using Snaps][docs].

### Installing snapd
The snap can be installed on any system that supports snaps. You can see how to install
snaps on your system [here](https://snapcraft.io/docs/installing-snapd/6735).

However for full security confinement, the snap should be installed on an
Ubuntu 18.04 LTS or later (Desktop or Server), or a system running Ubuntu Core 18 or later.

### Installing EdgeX Device Modbus as a snap
The snap is published in the snap store at https://snapcraft.io/edgex-device-modbus.
You can see the current revisions available for your machine's architecture by running the command:

```bash
$ snap info edgex-device-modbus
```

The latest stable version of the snap can be installed using:

```bash
$ sudo snap install edgex-device-modbus
## Build from source
Execute the following command from the top-level directory of this repo:
```

The 2.0 (Ireland) release of the snap can be installed using:

```bash
$ sudo snap install edgex-device-modbus --channel=2.0
```

The latest development version of the snap can be installed using:

```bash
$ sudo snap install edgex-device-modbus --edge
snapcraft
```

**Note** - the snap has only been tested on Ubuntu Core, Desktop, and Server.


## Snap configuration

Device services implement a service dependency check on startup which ensures that all of the runtime dependencies of a particular service are met before the service transitions to active state.

Snapd doesn't support orchestration between services in different snaps. It is therefore possible on a reboot for a device service to come up faster than all of the required services running in the main edgexfoundry snap. If this happens, it's possible that the device service repeatedly fails startup, and if it exceeds the systemd default limits, then it might be left in a failed state. This situation might be more likely on constrained hardware (e.g. RPi).

This snap therefore implements a basic retry loop with a maximum duration and sleep interval. If the dependent services are not available, the service sleeps for the defined interval (default: 1s) and then tries again up to a maximum duration (default: 60s). These values can be overridden with the following commands:

To change the maximum duration, use the following command:

```bash
$ sudo snap set edgex-device-modbus startup-duration=60
```

To change the interval between retries, use the following command:

```bash
$ sudo snap set edgex-device-modbus startup-interval=1
```

The service can then be started as follows. The "--enable" option
ensures that as well as starting the service now, it will be automatically started on boot:

This will create a snap package file with `.snap` extension. It can be installed locally by setting the `--dangerous` flag:
```bash
$ sudo snap start --enable edgex-device-modbus.device-modbus
sudo snap install --dangerous <snap-file>
```

### Using a content interface to set device configuration
The [snapcraft overview](https://snapcraft.io/docs/snapcraft-overview) provides additional details.

The `device-config` content interface allows another snap to seed this device
snap with both a configuration file and one or more device profiles.
### Obtain a Secret Store token
The `edgex-secretstore-token` snap slot makes it possible to automatically receive a token from a locally installed platform snap.

To use, create a new snap with a directory containing the configuration and device
profile files. Your snapcraft.yaml file then needs to define a slot with
read access to the directory you are sharing.

```
slots:
device-config:
interface: content
content: device-config
read:
- $SNAP/config
```

where `$SNAP/config` is configuration directory your snap is providing to
the device snap.

Then connect the plug in the device snap to the slot in your snap,
which will replace the configuration in the device snap. Do this with:
If the snap is built and installed locally, the interface will not auto-connect. You can check the status of the connections by running the `snap connections edgex-device-modbus` command.

To manually connect and obtain a token:
```bash
$ sudo snap connect edgex-device-modbus:device-config your-snap:device-config
sudo snap connect edgexfoundry:edgex-secretstore-token edgex-device-modbus:edgex-secretstore-token
```

This needs to be done before the device service is started for the first time.
Once you have set the configuration the device service can be started and
it will then be configurated using the settings you provided:

```bash
$ sudo snap start edgex-device-modbus.device-modbus
```

**Note** - content interfaces from snaps installed from the Snap Store that have the same publisher connect automatically. For more information on snap content interfaces please refer to the snapcraft.io [Content Interface](https://snapcraft.io/docs/content-interface) documentation.

### Autostart
By default, the edgex-device-modbus snap disables its service on install, as the expectation is that the default profile configuration files will be customized, and thus this behavior allows the profile ```configuration.toml``` files in $SNAP_DATA to be modified before the service is first started.

This behavior can be overridden by setting the ```autostart``` configuration setting to "true". This is useful when configuration and/or device profiles are being provided via configuration or gadget snap content interface.

**Note** - this option is typically set from a gadget snap.

### Rich Configuration
While it's possible on Ubuntu Core to provide additional profiles via gadget
snap content interface, quite often only minor changes to existing profiles are required.

These changes can be accomplished via support for EdgeX environment variable
configuration overrides via the snap's configure and install hooks.
If the service has already been started, setting one of these overrides currently requires the
service to be restarted via the command-line or snapd's REST API.
If the overrides are provided via the snap configuration defaults capability of a gadget snap,
the overrides will be picked up when the services are first started.

The following syntax is used to specify service-specific configuration overrides:
Please refer [here][secret-store-token] for further information.


```env.<stanza>.<config option>```

For instance, to setup an override of the service's Port use:

```$ sudo snap set edgex-device-modbus env.service.port=2112```

And restart the service:

```$ sudo snap restart edgex-device-modbus.device-modbus```

**Note** - at this time changes to configuration values in the [Writable] section are not supported.

For details on the mapping of configuration options to Config options, please refer to [Service Environment Configuration Overrides](#service-environment-configuration-overrides) below.

## Service Environment Configuration Overrides

**Note** - all of the configuration options below must be specified with the prefix: 'env.'

```
[Service]
service.health-check-interval // Service.HealthCheckInterval
service.host // Service.Host
service.server-bind-addr // Service.ServerBindAddr
service.port // Service.Port
service.max-result-count // Service.MaxResultCount
service.max-request-size // Service.MaxRequestSize
service.startup-msg // Service.StartupMsg
service.request-timeout // Service.RequestTimeout

[Clients.core-data]
clients.core-data.port // Clients.core-data.Port

[Clients.core-metadata]
clients.core-metadata.port // Clients.core-metadata.Port

[Device]
device.update-last-connected // Device.UpdateLastConnected
device.use-message-bus // Device.UseMessageBus
```
[edgex-device-modbus]: https://snapcraft.io/edgex-device-modbus
[docs]: https://docs.edgexfoundry.org/2.2/getting-started/Ch-GettingStartedSnapUsers/#device-modbus
[secret-store-token]: https://docs.edgexfoundry.org/2.2/getting-started/Ch-GettingStartedSnapUsers/#secret-store-token