Skip to content

Commit 05ce370

Browse files
Reapor-YurneroReapor-Yurnero
committed
update docs
1 parent 090fcc6 commit 05ce370

File tree

2 files changed

+184
-5
lines changed

2 files changed

+184
-5
lines changed

‎docs/init.md‎

Lines changed: 183 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,9 @@
33
In this guide, most of the operations should be done on the swagger API page.
44
If you do not change port settings, it should be on <http://localhost:9000/brickapi/v1/docs>.
55

6-
## Register user
6+
## Setup User
7+
8+
### Register User
79

810
=== "Username / Password"
911

@@ -50,14 +52,191 @@ If you do not change port settings, it should be on <http://localhost:9000/brick
5052
User can also be registered in the frontend.
5153
However, it is recommanded to use the Swagger API for convenience of debugging the setup.
5254

53-
## Set superuser
55+
### Set Superuser
5456

5557
Use the API `POST /brickapi/v1/users/init_superuser` to set the current user as superuser.
5658
This API can only be called when no superuser exist in the system.
5759

5860

59-
## Create domain
61+
## Setup Domain
62+
63+
### Create Domain
6064

6165
1. Use the API `POST /brickapi/v1/domains/{domain}` to create a new domain.
66+
6267
`domain` should be set to the name of the domain.
63-
2.
68+
69+
2. Use the API `GET /brickapi/v1/domains/{domain}/init` to init the domain.
70+
71+
`domain` should be set to the name set in step 1.
72+
73+
3. Use the API `GET /brickapi/v1/domains/{domain}/upload` to upload a `.ttl` file.
74+
75+
An example file `center_hall.ttl` can be found in `projects/sbos-playground/examples/data/`.
76+
77+
!!! info
78+
79+
The uploaded brick schema can be examined in the GraphDB GUI.
80+
By default, <http://127.0.0.1:37200/>.
81+
82+
### Add User to Domain
83+
84+
Use the API `POST /brickapi/v1/domains/{domain}/users/{user}` to add a user to a domain.
85+
86+
`domain` should be set to the domain name.
87+
88+
`user` should be set to the email of the user.
89+
90+
91+
92+
### Create User Profile
93+
94+
Use the API `POST /brickapi/v1/profiles/` to create a user profile.
95+
96+
97+
!!! example
98+
99+
```json title="Request Body"
100+
{
101+
"name": "profile1",
102+
"read": "SELECT ?p WHERE {{ ?e brick:feeds {room} . ?e brick:hasPoint ?p . ?p a ?o . FILTER (?o IN (brick:Temperature_Sensor, brick:Occupancy_Sensor, brick:On_Off_Command, brick:CO2_Sensor, brick:Warm_Cool_Adjust_Sensor)) }}",
103+
"write": "SELECT ?p WHERE {{ ?e brick:feeds {room} . ?p brick:isPointOf ?e . ?p a brick:Warm_Cool_Adjust_Sensor .}}",
104+
"arguments": {
105+
"room": "brick:Room"
106+
}
107+
}
108+
```
109+
110+
A profile "profile1" will be created. The API will return
111+
112+
```json title="Response Body"
113+
{
114+
"errorCode": "Success",
115+
"errorMessage": "",
116+
"showType": 0,
117+
"data": {
118+
"id": "<ObjectId>",
119+
"name": "profile1",
120+
"read": "SELECT ?p WHERE {{ ?e brick:feeds {room} . ?e brick:hasPoint ?p . ?p a ?o . FILTER (?o IN (brick:Temperature_Sensor, brick:Occupancy_Sensor, brick:On_Off_Command, brick:CO2_Sensor, brick:Warm_Cool_Adjust_Sensor)) }}",
121+
"write": "SELECT ?p WHERE {{ ?e brick:feeds {room} . ?p brick:isPointOf ?e . ?p a brick:Warm_Cool_Adjust_Sensor .}}",
122+
"arguments": {
123+
"room": "brick:Room"
124+
}
125+
}
126+
}
127+
```
128+
129+
Note that a profile is identified by its `id` (ObjectId), not by its `name`
130+
because there may exist duplicate profile names in the system.
131+
132+
!!! warning
133+
134+
Currently, user profiles are shared among domains. It may be changed in future updates.
135+
136+
### Assign Profile to User
137+
138+
Use the API `POST /brickapi/v1/domains/{domain}/users/{user}/profiles` to assign a user profile to a domain user.
139+
140+
!!! example
141+
142+
```json title="Request Body"
143+
{
144+
"profile": "<ObjectId>",
145+
"arguments": {
146+
"room": "Center_Hall:101"
147+
}
148+
}
149+
```
150+
151+
Remember to use the profile id created in the last step.
152+
153+
154+
## Setup App
155+
156+
### Create App
157+
158+
Use the API `POST /brickapi/v1/apps` to create an app.
159+
160+
!!! example
161+
162+
```json title="Request Body"
163+
{
164+
"name": "genie",
165+
"description": ""
166+
}
167+
```
168+
169+
An app "genie" will be created.
170+
171+
### Upload App Data
172+
173+
Use the API `POST /brickapi/v1/apps/{app}/submit`
174+
to submit frontend, backend, permission profile and permission model of an app.
175+
176+
!!! example
177+
178+
| Form Argument | Value |
179+
| -------- | ------- |
180+
| frontend_file | An archive (zip, tar) of the frontend files |
181+
| backend_file | An archive (zip, tar) of the backend files |
182+
| permission_profile_read | `SELECT ?p WHERE {{ ?e brick:feeds {room} . ?e brick:hasPoint ?p . ?p a ?o . FILTER (?o IN (brick:Temperature_Sensor, brick:Occupancy_Sensor, brick:CO2_Sensor, brick:Warm_Cool_Adjust_Sensor)) }}` |
183+
| permission_profile_write | `SELECT ?p WHERE {{ ?e brick:feeds {room} . ?e brick:hasPoint ?p . ?p a ?o . FILTER (?o IN (brick:On_Off_Command, brick:Warm_Cool_Adjust_Sensor)) }}` |
184+
| permission_profile_arguments | `{"room": "brick:Room", "sensor": "brick:Temperature_Sensor", "setpoint": "brick:Temperature_Setpoint"}` |
185+
| permission_model | intersection |
186+
187+
### Approve App
188+
189+
An app need to be approved before it can be installed by users.
190+
191+
Use the API `POST /brickapi/v1/apps/{app}/approve` to approve it.
192+
193+
### Build App (by Docker)
194+
195+
The backend files of an app submitted before should contain a `Dockerfile`.
196+
197+
Use the API `/brickapi/v1/apps/{app}/build` to build the app backend with the `Dockerfile`.
198+
199+
Please wait for a while because it takes some time to build the docker image.
200+
201+
!!! note
202+
203+
A detailed build log is returned by the API. It can be used to verify whether the build succedded.
204+
205+
### Add App to Domain
206+
207+
Use the API `POST /brickapi/v1/domains/{domain}/apps/{app}` to approve the app in a domain
208+
(usually this step is done by a domain admin).
209+
210+
!!! note
211+
212+
Use the API `GET /brickapi/v1/domains/{domain}/apps` to list all approved apps in a domain
213+
and find whether the app is successfully added.
214+
215+
## Use App
216+
217+
### Install App
218+
219+
Use the API `POST /brickapi/v1/users/domains/{domain}/apps/{app}` to install an app for a user.
220+
221+
### Set App Arguments
222+
223+
Use the API `/brickapi/v1/users/domains/{domain}/apps/{app}` to set the arguments of an app for a user.
224+
225+
!!! example
226+
227+
```json title="Request Body"
228+
{
229+
"room": "Center_Hall:101",
230+
"sensor": "Center_Hall:AH-6.RA-T",
231+
"setpoint": "Center_Hall:AH-6.EFFHTG-SP"
232+
}
233+
```
234+
235+
### Start App
236+
237+
Use the API `POST /brickapi/v1/users/domains/{domain}/apps/{app}/start` to start an app for a user.
238+
239+
A container named `sbos-playground-<app>-<user>-<id>` will be created and started.
240+
It should be listed in the `docker ps` command.
241+
242+

‎docs/tutorial/buildsys2024.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Tutorial@BuildSys24 (Hangzhou!)
1+
# Tutorial@CPS-IoT Week 25 (Irvine!)
22

33
## What is Playground and why does it matter?
44
Adoption of building apps in practice is slow for two safety reasons:

0 commit comments

Comments
 (0)