Skip to content

Commit d90b08d

Browse files
leandrofarsleandrofars
authored
Merge pull request #6 from leonardomeres/main
doc: Updates README.md with information about how to configure and use the agent simulator
2 parents 482c3f1 + 67ef19c commit d90b08d

File tree

2 files changed

+146
-31
lines changed

2 files changed

+146
-31
lines changed

‎README.md‎

Lines changed: 146 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,149 @@
11
<p align="center">
22
<img src="https://github.com/OktopUSP/agent-sim/assets/83298718/c9a6347d-4576-4ae1-a1ba-7a0c28883855"/>
33
</p>
4-
<br/>
5-
<ul>
6-
<li>
7-
<h4>Introduction:</h4>
8-
</li>
9-
</ul>
10-
<p>
11-
This repository aims to promote the development of an agent TR-369 simulator to be used as an example of the protocol behavior in a embedded device. Our project is made based on <a href="https://github.com/BroadbandForum/obuspa" target="_blank">obuspa</a>.
12-
</p>
13-
<ul>
14-
<li>
15-
<h4>Usage:</h4>
16-
<ul>
17-
<li>
18-
Load tests
19-
</li>
20-
<li>
21-
Controller development without specific hardware
22-
</li>
23-
<li>
24-
Simulate real-world operations
25-
</li>
26-
<li>
27-
Try TR-369 without buying devices
28-
</li>
29-
<li>
30-
Exploit controller vulnerabilities
31-
</li>
32-
</ul>
33-
</li>
34-
</ul>
4+
5+
# Introduction
6+
This repository aims to promote the development of an agent TR-369 simulator to be used as an example of the protocol behavior in a embedded device. Our project is made based on [obuspa](https://github.com/BroadbandForum/obuspa).
7+
8+
## Features
9+
- Load tests
10+
- Controller development without specific hardware
11+
- Simulate real-world operations
12+
- Try TR-369 without buying devices
13+
- Exploit controller vulnerabilities
14+
15+
### Usage
16+
This simulator works by loading the Obusba project inside a docker container. There are several possible configurations you can customize.
17+
18+
**Requisites to run:**
19+
- Docker
20+
- GO
21+
22+
Before running the simulator make sure you download all go modules:
23+
24+
```shell
25+
agent@sim:/home/apps/agent-sim$ go mod download
26+
agent@sim:/home/apps/GitHub/agent-sim$ go mod tidy
27+
```
28+
29+
It’s possible to configure flags either through the command line or by using the **.env** file in the project root folder. Below are the details for each available configuration flag:
30+
31+
**Options**
32+
33+
| CMD Argument | ENV | Default | Description |
34+
|-----------------|------------------|-------------|--------------------------------------------|
35+
| `-sim_number` | `SIM_NUM` | `1` | Number of simulated devices |
36+
| `-num_to_start_ids` | `NUM_TO_START_IDS` | `0` | From where to start your IDs |
37+
| `-protocol` | `MTP` | `""` | MTP to use (mqtt, stomp, websockets) |
38+
| `-mqtt_addr` | `MQTT_ADDR` | `localhost` | Address of the mqtt broker |
39+
| `-mqtt_port` | `MQTT_PORT` | `1883` | Port of the mqtt broker |
40+
| `-mqtt_user` | `MQTT_USER` | `""` | Mqtt user |
41+
| `-mqtt_passwd` | `MQTT_PASSWD` | `""` | Mqtt password |
42+
| `-mqtt_ssl` | `MQTT_SSL` | `false` | Mqtt with tls/ssl |
43+
| `-ws_addr` | `WS_ADDR` | `localhost` | Address of the websockets server |
44+
| `-ws_port` | `WS_PORT` | `8080` | Port of the websockets server |
45+
| `-ws_route` | `WS_ROUTE` | `/ws/agent` | Route of the websockets server |
46+
| `-ws_ssl` | `WS_SSL` | `false` | Websockets with tls/ssl |
47+
| `-path` | `PATH` | `""` | Folder path to save configurations |
48+
| `-imgpath` | `DOCKERFILE_PATH`| `""` | Path to Dockerfile |
49+
| `-prefix` | `PREFIX` | `oktopus` | Prefix of device id |
50+
51+
The application processes flags in the following order of priority:
52+
```txt
53+
1º - Flag through command line.
54+
2º - Env variables.
55+
3º - Default flag value.
56+
```
57+
58+
**Command Line Examples**
59+
60+
Running a simulated MQTT client:
61+
```shell
62+
go run cmd/main.go -path=/home/apps/agent-sim/configs/ -protocol=mqtt -mqtt_addr=192.168.10.159 -mqtt_port=1883
63+
```
64+
65+
If the command succeeds, a Docker container will be built and run:
66+
67+
```shell
68+
2025/09/09 15:54:19 Loaded variables from '.env'
69+
2025/09/09 15:54:19 main.go:50: Starting Oktopus TR-369 Agent Simulator Version: 0.0.1
70+
{"stream":"Step 1/21 : FROM ubuntu AS build-env"}
71+
{"stream":"\n"}
72+
{"stream":" ---\u003e 802541663949\n"}
73+
{"stream":"Step 2/21 : RUN apt update \u0026\u0026 apt -y install build-essential libssl-dev libcurl4-openssl-dev libsqlite3-dev libz-dev autoconf automake libtool libmosquitto-dev pkg-config git cmake make \u0026\u0026 apt clean"}
74+
{"aux":{"ID":"sha256:0d679f9e9582039599dafbca24a3a153415ae22244fe5ad0fe99aecf53fb3f1f"}}
75+
{"stream":"Successfully built 0d679f9e9582\n"}
76+
{"stream":"Successfully tagged obuspa:latest\n"}
77+
2025/09/09 15:54:20 mqtt.go:29: Create new agent(s) with mqtt protocol
78+
2025/09/09 15:54:20 mqtt.go:30: Mqtt client config: {Addr:192.168.10.159 Port:1883 User: Pass: Ssl:false}
79+
2025/09/09 15:54:20 mqtt.go:47: Device: oktopus-0
80+
2025/09/09 15:54:20 container.go:125: Container oktopus-0-mqtt started
81+
```
82+
83+
Container **oktopus-0-mqtt** was created and will simulate a mqtt client connecting to host 192.168.10.159 on port 1883.
84+
85+
Running 100 simulated mqtt clients:
86+
```shell
87+
go run cmd/main.go -sim_number=100 -path=/home/apps/agent-sim/configs/ -protocol=mqtt -mqtt_addr=192.168.10.159 -mqtt_port=1883
88+
```
89+
100 docker containers will be created in this case. You can check them by using **docker ps** command:
90+
```shell
91+
docker ps
92+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
93+
0a845c29eea7 obuspa:latest "obuspa -p -v 4 -r /…" 19 seconds ago Up 13 seconds oktopus-70-mqtt
94+
ac41a997c6b3 obuspa:latest "obuspa -p -v 4 -r /…" 19 seconds ago Up 11 seconds oktopus-82-mqtt
95+
999d5c888e49 obuspa:latest "obuspa -p -v 4 -r /…" 19 seconds ago Up 13 seconds oktopus-19-mqtt
96+
e81bf0d80e67 obuspa:latest "obuspa -p -v 4 -r /…" 19 seconds ago Up 14 seconds oktopus-7-mqtt
97+
3e3230a7a2b4 obuspa:latest "obuspa -p -v 4 -r /…" 19 seconds ago Up 14 seconds oktopus-9-mqtt
98+
416621cc1af3 obuspa:latest "obuspa -p -v 4 -r /…" 19 seconds ago Up 11 seconds oktopus-81-mqtt
99+
ef6127c163ae obuspa:latest "obuspa -p -v 4 -r /…" 19 seconds ago Up 10 seconds oktopus-11-mqtt
100+
6cae0db74dd6 obuspa:latest "obuspa -p -v 4 -r /…" 19 seconds ago Up 13 seconds oktopus-62-mqtt
101+
451f8b65332a obuspa:latest "obuspa -p -v 4 -r /…" 19 seconds ago Up 10 seconds oktopus-66-mqtt
102+
55b11d721707 obuspa:latest "obuspa -p -v 4 -r /…" 19 seconds ago Up 9 seconds oktopus-67-mqtt
103+
088fda26ed68 obuspa:latest "obuspa -p -v 4 -r /…" 19 seconds ago Up 16 seconds oktopus-87-mqtt
104+
61f93f6dfd13 obuspa:latest "obuspa -p -v 4 -r /…" 19 seconds ago Up 11 seconds oktopus-80-mqtt
105+
67288fc7e2d8 obuspa:latest "obuspa -p -v 4 -r /…" 19 seconds ago Up 14 seconds oktopus-64-mqtt
106+
```
107+
108+
To stop and remove all containers type **ctrl+c**:
109+
```shell
110+
^C2025/09/09 16:04:50 mqtt.go:160: Deleted docker mqtt container: 1c93a54521dac6f1d811cd506e65d15b6b7870a0363d32516db74ff163484583
111+
2025/09/09 16:04:50 mqtt.go:160: Deleted docker mqtt container: 5c936835a39ffc5be37d861041e808c52b9cfe1cb182198c404a0b6e2da576e4
112+
2025/09/09 16:04:50 mqtt.go:160: Deleted docker mqtt container: 7c0844585f3b4e9cfa387c334ebd0cbedfb9ba55e30573030dff8ea885232515
113+
2025/09/09 16:04:50 main.go:121: (⌐■_■) Agent simulator is out!
114+
```
115+
116+
**ENV files examples**
117+
118+
You can also set flags using the **.env** file. For example:
119+
120+
Running 100 simulated mqtt clients:
121+
122+
Set necessary flags inside the .env file:
123+
```txt
124+
SIM_NUM="100"
125+
NUM_TO_START_IDS=""
126+
MTP="mqtt"
127+
PREFIX=""
128+
MQTT_USER="mqttuser"
129+
MQTT_PASSWd="mqttpass"
130+
MQTT_PORT="1883"
131+
MQTT_ADDR="192.168.10.159"
132+
WS_ROUTE=""
133+
WS_ADDR=""
134+
PATH="/home/apps/agent-sim/configs/"
135+
DOCKERFILE_PATH="./Dockerfile"
136+
MTP="mqtt" #options = mqtt, websockets or stomp
137+
```
138+
139+
After flags are set in the .env file you can run the simulator using the bellow command:
140+
141+
```shell
142+
go run cmd/main.go
143+
```
144+
145+
**Controller View**
146+
147+
After running the agent simulator you can view them at the Devices page from the Oktopus controller:
148+
149+
![alt text](/img/devices.png)

‎img/devices.png‎

224 KB
Loading

0 commit comments

Comments
 (0)