Skip to content

Commit ad27ad0

Browse files
rnovatorovrnovatorov
authored
Merge pull request #13 from Enapter/nvk/snmp-vucm-example
adding example for standalone UCM for monitoring Eaton UPS over SNMP
2 parents be43f7c + 3672135 commit ad27ad0

9 files changed

Lines changed: 430 additions & 11 deletions

File tree

‎examples/vucm/snmp-eaton-ups/Dockerfile‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
FROM python:3.10-alpine3.16
2+
3+
WORKDIR /app
4+
5+
RUN apk add build-base
6+
7+
RUN python -m venv .venv
8+
COPY requirements.txt requirements.txt
9+
RUN .venv/bin/pip install -r requirements.txt
10+
11+
COPY script.py script.py
12+
13+
CMD [".venv/bin/python", "script.py"]

‎examples/vucm/snmp-eaton-ups/README.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Eaton UPS Standalone UCM (SNMP)
2+
3+
This example describes the implementation of the [Standalone UCM](https://handbook.enapter.com/software/virtual_ucm/) concept using the opensource [Enapter python-sdk](https://github.com/Enapter/python-sdk) for monitoring Eaton UPS using SNMP protocol.
4+
5+
In order to use this UCM you need to enable SNMPv1 protocol in the Web Interface of your UPS and set unique community name for the read only access. The default port for SNMP is 161 but also can be changed.
6+
7+
As an example in this guide we will use the following dummy settings for configuration:
8+
9+
UPS IP Address: 192.168.192.192
10+
11+
Community Name: public
12+
13+
SNMP Port: 161
14+
15+
## Requirements
16+
17+
It is recommended to run this UCM using Docker and Docker Compose. This will ensure that environment is correct.
18+
19+
The UPS must be reachable from the computer where the Docker Container will be running. You can check availability and settings with `snmpget` command on Linux or Mac:
20+
21+
```bash
22+
user@pc snmp-eaton-ups % snmpget -v1 -c public 192.168.192.192:161 1.3.6.1.2.1.33.1.1.1.0
23+
SNMPv2-SMI::mib-2.33.1.1.1.0 = STRING: "EATON"
24+
```
25+
26+
## Step 1. Create Standalone UCM in Enapter Cloud
27+
28+
Log in to the Enapter Cloud, navigate to the Site where you want to create Standalone UCM and click on `Add new` button in the Standalone Device section.
29+
30+
After creating Standalone UCM, you need to Generate and save Configuration string also known as ENAPTER_VUCM_BLOB as well as save UCM ID which will be needed for the next step
31+
32+
More information you can find on [this page](https://developers.enapter.com/docs/tutorial/software-ucms/standalone).
33+
34+
## Step 2. Upload Blueprint into the Cloud
35+
36+
The general case [Enapter Blueprint](https://marketplace.enapter.com/about) consists of two files - declaration in YAML format (manifest.yaml) and logic written in Lua. Howerver for this case the logic is written in Python as Lua implementation doesn't have SNMP integration.
37+
38+
But for both cases we need to tell Enapter Cloud which telemetry we are going to send and store and how to name it.
39+
40+
The easiest way to do that - using [Enapter CLI](https://github.com/Enapter/enapter-cli) to upload manifest.yaml into Cloud. The other option is to use [Web IDE](https://developers.enapter.com/docs/tutorial/uploading-blueprint).
41+
42+
```bash
43+
user@pc snmp-eaton-ups % enapter devices upload --blueprint-dir . --hardware-id REAL_UCM_ID
44+
upload started with operation id 25721
45+
[#25721] 2023-07-20T16:27:33Z [INFO] Started uploading blueprint[id=dcb05efe-1618-4b01-877b-6105960690bc] on device[hardware_id=REAL_UCM_ID]
46+
[#25721] 2023-07-20T16:27:33Z [INFO] Generating configuration for uploading
47+
[#25721] 2023-07-20T16:27:33Z [INFO] Updating configuration in the cloud platform
48+
[#25721] 2023-07-20T16:27:33Z [INFO] Updating configuration on the gateway
49+
[#25721] 2023-07-20T16:27:35Z [INFO] Uploading blueprint finished successfully
50+
Done!
51+
```
52+
53+
## Step 3. Configuring Standalone UCM
54+
55+
Open `docker-compose.yaml` in any editor.
56+
57+
Set environment variables according to your configuration settings. With dummy settings your file will look like this:
58+
59+
```yaml
60+
version: "3"
61+
services:
62+
snmp-eaton-ups-ucm:
63+
build: .
64+
image: enapter-vucm-examples/snmp-eaton-ups:latest
65+
environment:
66+
ENAPTER_VUCM_BLOB: "REALENAPTERVUCMBLOBMUSTBEHERE="
67+
ENAPTER_SNMP_HOST: "192.168.192.192"
68+
ENAPTER_SNMP_PORT: "161"
69+
ENAPTER_SNMP_COMMUNITY: "public"
70+
```
71+
72+
## Step 4. Build Docker Image with Standalone UCM
73+
74+
> You can you can skip this step and go directly to th Step 5.
75+
> Docker Compose will automatically build your image before starting container.
76+
77+
Build your Docker image by running `bash docker_build.sh` command in directory with UCM.
78+
79+
```bash
80+
user@pc snmp-eaton-ups % bash docker_build.sh
81+
#0 building with "desktop-linux" instance using docker driver
82+
83+
#1 [internal] load .dockerignore
84+
#1 transferring context: 2B done
85+
#1 DONE 0.0s
86+
87+
#2 [internal] load build definition from Dockerfile
88+
#2 transferring dockerfile: 281B done
89+
#2 DONE 0.0s
90+
91+
#3 [internal] load metadata for docker.io/library/python:3.10-alpine3.16
92+
#3 DONE 2.0s
93+
94+
#4 [1/7] FROM docker.io/library/python:3.10-alpine3.16@sha256:afe68972cc00883d70b3760ee0ffbb7375cf09706c122dda7063ffe64c5be21b
95+
#4 DONE 0.0s
96+
97+
#5 [internal] load build context
98+
#5 transferring context: 66B done
99+
#5 DONE 0.0s
100+
101+
#6 [3/7] RUN apk add build-base
102+
#6 CACHED
103+
104+
#7 [2/7] WORKDIR /app
105+
#7 CACHED
106+
107+
#8 [4/7] RUN python -m venv .venv
108+
#8 CACHED
109+
110+
#9 [5/7] COPY requirements.txt requirements.txt
111+
#9 CACHED
112+
113+
#10 [6/7] RUN .venv/bin/pip install -r requirements.txt
114+
#10 CACHED
115+
116+
#11 [7/7] COPY script.py script.py
117+
#11 CACHED
118+
119+
#12 exporting to image
120+
#12 exporting layers done
121+
#12 writing image sha256:92e1050debeabaff5837c6ca5bc26b0b966d09fc6f24e21b1d10cbb2f4d9aeec done
122+
#12 naming to docker.io/enapter-vucm-examples/snmp-eaton-ups:latest done
123+
#12 DONE 0.0s
124+
```
125+
126+
Your `enapter-vucm-examples/snmp-eaton-ups` image is now built and you can see it by running `docker images` command:
127+
128+
```bash
129+
user@pc snmp-eaton-ups % docker images enapter-vucm-examples/snmp-eaton-ups
130+
REPOSITORY TAG IMAGE ID CREATED SIZE
131+
enapter-vucm-examples/snmp-eaton-ups latest 92e1050debea 5 hours ago 285MB
132+
```
133+
134+
## Step 5. Run your Standalone UCM Docker Container
135+
136+
Finally run your Standalone UCM with `docker-compose up` command:
137+
138+
```bash
139+
user@pc snmp-eaton-ups % docker-compose up
140+
[+] Running 1/0
141+
✔ Container snmp-eaton-ups-snmp-eaton-ups-ucm-1 Created 0.0s
142+
Attaching to snmp-eaton-ups-snmp-eaton-ups-ucm-1
143+
snmp-eaton-ups-snmp-eaton-ups-ucm-1 | {"time": "2023-07-20T15:50:01.570744", "level": "INFO", "name": "enapter.mqtt.client", "host": "10.1.1.47", "port": 8883, "message": "starting"}
144+
snmp-eaton-ups-snmp-eaton-ups-ucm-1 | {"time": "2023-07-20T15:50:21.776037", "level": "INFO", "name": "enapter.mqtt.client", "host": "10.1.1.47", "port": 8883, "message": "client ready"}
145+
```
146+
147+
On this step you can check that your UCM is now Online in the Cloud.

‎examples/vucm/snmp-eaton-ups/docker-compose.yaml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
version: "3"
2+
services:
3+
snmp-eaton-ups-ucm:
4+
build: .
5+
image: enapter-vucm-examples/snmp-eaton-ups:latest
6+
stop_signal: SIGINT
7+
environment:
8+
ENAPTER_VUCM_BLOB: "REALENAPTERVUCMBLOBMUSTBEHERE="
9+
ENAPTER_SNMP_HOST: "192.168.192.192"
10+
ENAPTER_SNMP_PORT: "161"
11+
ENAPTER_SNMP_COMMUNITY: "public"

‎examples/vucm/snmp-eaton-ups/docker_build.sh‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
#!/bin/bash
2+
3+
set -euo pipefail
4+
IFS=$'\n\t'
5+
6+
SCRIPT_DIR="$(realpath "$(dirname "$0")")"
7+
IMAGE_TAG="${IMAGE_TAG:-"enapter-vucm-examples/$(basename "$SCRIPT_DIR"):latest"}"
8+
9+
docker build --progress=plain --tag "$IMAGE_TAG" "$SCRIPT_DIR"

‎examples/vucm/snmp-eaton-ups/docker_run.sh‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
#!/bin/bash
2+
3+
set -euo pipefail
4+
IFS=$'\n\t'
5+
6+
SCRIPT_DIR="$(realpath "$(dirname "$0")")"
7+
IMAGE_TAG="${IMAGE_TAG:-"enapter-vucm-examples/$(basename "$SCRIPT_DIR"):latest"}"
8+
9+
bash $SCRIPT_DIR/docker_build.sh
10+
11+
docker run --rm -it \
12+
--network host \
13+
-e ENAPTER_LOG_LEVEL="${ENAPTER_LOG_LEVEL:-info}" \
14+
-e ENAPTER_VUCM_BLOB="$ENAPTER_VUCM_BLOB" \
15+
-e ENAPTER_SNMP_HOST="$ENAPTER_SNMP_HOST" \
16+
-e ENAPTER_SNMP_PORT="$ENAPTER_SNMP_PORT" \
17+
-e ENAPTER_SNMP_COMMUNITY="$ENAPTER_SNMP_COMMUNITY" \
18+
"$IMAGE_TAG"

‎examples/vucm/snmp-eaton-ups/manifest.yml‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
blueprint_spec: "device/1.0"
2+
3+
display_name: "Eaton UPS SNMP"
4+
icon: enapter-battery-storage
5+
license: MIT
6+
author: enapter
7+
support:
8+
url: https://go.enapter.com/enapter-blueprint-support
9+
email: support@enapter.com
10+
11+
communication_module:
12+
product: ENP-VIRTUAL
13+
14+
properties:
15+
manufacturer:
16+
display_name: Manufacturer
17+
type: string
18+
model:
19+
display_name: Model
20+
type: string
21+
fw_ver:
22+
display_name: UPS Firmware version
23+
type: string
24+
agent_ver:
25+
display_name: Agent Software Version
26+
type: string
27+
28+
telemetry:
29+
temperature:
30+
display_name: Temperature
31+
type: integer
32+
unit: "°C"
33+
capacity:
34+
display_name: Battery Capacity
35+
type: integer
36+
unit: "%"
37+
status:
38+
type: string
39+
display_name: Battery Status
40+
enum:
41+
"1":
42+
display_name: Charging
43+
"2":
44+
display_name: Discharging
45+
"3":
46+
display_name: Floating
47+
"4":
48+
display_name: Resting
49+
"5":
50+
display_name: unknown
51+
"6":
52+
display_name: Disconnected
53+
"7":
54+
display_name: Under Test
55+
"8":
56+
display_name: Check Battery
57+
grid_freq:
58+
type: integer
59+
display_name: Grid Frequency
60+
unit: "Hz"
61+
ups_freq:
62+
type: integer
63+
display_name: UPS Output Frequency
64+
unit: "Hz"
65+
grid_v:
66+
type: integer
67+
display_name: Grid Voltage
68+
unit: "V"
69+
out_load:
70+
type: integer
71+
display_name: UPS Load
72+
unit: "%"
73+
ac_out_active_power:
74+
type: integer
75+
display_name: UPS Output Power
76+
unit: "W"
77+
78+
.cloud:
79+
category: renewable_energy_sources
80+
mobile_main_chart: ac_out_active_power
81+
mobile_telemetry:
82+
- capacity
83+
- battery_status
84+
- grid_v
85+
- out_load
86+
- temperature
87+
- grid_freq
88+
- ups_freq
89+
90+
mobile_charts:
91+
- temperature
92+
- capacity
93+
- ac_out_active_power
94+
- grid_freq
95+
- ups_freq
96+
- grid_v
97+
- out_load

‎examples/vucm/snmp-eaton-ups/requirements.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
pysnmp==4.4.12
2+
pyasn1<=0.4.8
3+
enapter==0.8.0

0 commit comments

Comments
 (0)