add docs/tutorial

Co-authored-by: tc-imba <[email protected]>
Co-authored-by: Reapor-Yurnero <[email protected]>

Author: tc-imba

docs/tutorial/write_a_permission_profile.md

@@ -0,0 +1,29 @@
+# Write a Permission Profile
+
+A permission profile is a function-like object that takes in a few Brick-typed arguments and returns two lists of building resources for read and (read plus) write capability respectively.
+The derivation of the two capability lists is defined by two SPARQL queries which use the provided arguments as parameters.
+Note that the permission profile is statically typed --- arguments must be of the specified Brick class.
+
+For example, this is a permission profile that takes `room` as an argument. 
+To distinguish arguments and normal brackets (`{` and `}`), you should escape them with (`{{` and `}}`) in the sparql query.
+
+```sparql
+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)
+    ) 
+}}
+```
+
+The arguments of the permission profile should be explicitly defined with their types in Brick.
+
+```json
+{"room":"brick:Room"}
+```

docs/tutorial/write_an_app.md

@@ -0,0 +1,158 @@
+# Write an App
+
+The folder `apps/demo` (https://github.com/BrickSchema/playground/tree/master/apps/demo) contains a demo app, which is a minimized read/write actuator with Brick and Playground
+interfaces.
+
+The demo app contains the following files:
+
+```text
+├── backend             # a simple backend written by express.js
+│  └── index.js         
+├── frontend            # a simple frontend in pure html
+│  └── index.html       
+├── build.sh            # a script that packs backend.zip and frontend.zip
+├── Dockerfile          # sbos-playground uses the Dockerfile to build the image
+├── package.json        # define the dependencies in the backend
+└── yarn.lock           # lock the dependencies in package.json
+```
+
+You can use any language and framework to write the app backend and frontend.
+
+## Backend
+
+### Dockerfile
+
+For the backend, you must provide a `Dockerfile` and other files (if necessary) to build the docker image.
+
+For example, the `Dockerfile` of the demo app use `node 18` as base image, install the packages and run the backend file `backend/index.js`. For more information about how to write a `Dockerfile`, please refer to the official documentation of `Docker`.
+
+!!! important
+    You should start the backend server on `localhost:5000` in the docker image so that it can be accessed by the frontend.
+
+```Dockerfile
+FROM node:18-alpine
+
+ENV HOME="/root"
+WORKDIR /root
+
+COPY ./package.json ./yarn.lock  /root/
+RUN --mount=type=cache,target=/usr/local/share/.config/yarn/global yarn
+COPY . /root
+
+CMD node backend/index.js
+```
+
+### Get JWT (JSON Web Token)
+
+When running the docker image, `playground` provides an environment variable `BRICK_SERVER_API_TOKEN`, which is a JWT (
+JSON Web Token) to authorize the requests to the API endpoints in `playground`.
+
+For example, the following code snippets get the JWT from the environment variable and parse the information in the JWT.
+
+=== "Python"
+
+    ```python
+    import os
+    import jwt
+    api_token = os.environ.get('BRICK_SERVER_API_TOKEN')
+    decoded_token = jwt.decode(api_token, options={"verify_signature": False})
+    ```
+
+=== "NodeJS"
+
+    ```js
+    const apiToken = process.env.BRICK_SERVER_API_TOKEN;    
+    const decodedToken = JSON.parse(Buffer.from(apiToken.split('.')[1], 'base64').toString());
+    ```
+
+The decoded (parsed) JWT is a JSON object, which is in the format of
+
+```json
+{
+  "sub": "[email protected]",
+  "aud": [
+    "brick"
+  ],
+  "domain": "Center_Hall",
+  "app": "demo",
+  "domain_user_app": "66c4ec995317281fb487ccd3",
+  "exp": 1747595485
+}
+```
+
+| Key             | Description                              |
+|-----------------|------------------------------------------|
+| sub             | User using this app                      |
+| aud             | JWT audience (always "brick")            |
+| domain          | The domain this app currently working in |
+| app             | Name of this app                         |
+| domain_user_app | ObjectId of this app instance in DB      |
+| exp             | Expiration time of the JWT (Unix Epoch)  |
+
+### Make API Requests to `playground`
+
+The backend should add the JWT in the header as a bearer token when sending API requests to `playground`
+
+```python
+headers = {
+  'Content-Type': 'application/json',
+  'Authorization': 'Bearer <JWT token>',
+}
+```
+
+The base API endpoint of `playground` is https://brickserver.ucsd.edu/brickapi/v1/, you can also check https://brickserver.ucsd.edu/brickapi/v1/docs for a detailed documentation of the available APIs.
+
+
+
+## Frontend
+
+For the frontend, you must provide a `index.html` and other files (such as `js`, `css` files if necessary), and the folder will be served as static files on `playground`.
+Though we only use a single html file as the frontend in the demo app, you can choose any frontend framework and use the build files as the frontend.
+
+### Get JWT
+
+When a user accesses the frontend through `playground`, the same JWT provided to the backend is included in the query parameter `token`. You can use `Javascript` to read the JWT.
+
+```js
+const baseURL = "https://brickserver.ucsd.edu/brickapi/v1/apps/api";
+const params = new URL(document.location).searchParams;
+const token = params.get("token");
+```
+
+### Make API Requests to Backend
+
+`playground` designed special API endpoint translation rules for the frontend to access to backend APIs.
+The base API endpoint for such API requests is https://brickserver.ucsd.edu/brickapi/v1/apps/api.
+
+For example, if the backend has an API endpoint on `localhost:5000/example`, the frontend should send a request to https://brickserver.ucsd.edu/brickapi/v1/apps/api/example with the JWT in the header as a bearer token (same as how it is used in the backend).
+
+## Submit the App
+
+### Backend and Frontend Files
+
+The backend and frontend files should be zipped into `backend.zip` and `frontend.zip` before submission. Make sure that the files are in the root of the zip archive.
+
+For example, the structure of `backend.zip` in the demo app is 
+
+```text
+backend.zip
+├── backend            
+│  └── index.js         
+├── Dockerfile          
+├── package.json        
+└── yarn.lock          
+```
+
+The structure of `frontend.zip` in the demo app is 
+
+```text
+frontend.zip
+└── index.html       
+```
+
+The file `build.sh` is a helper script to generate these two zip files in the demo app.
+
+### Permission Profile
+
+
+

mkdocs.yml

@@ -71,3 +71,4 @@ nav:
   - Tutorials:
       - Tutorial@CPSIoT25!: tutorial/cpsiot25.md
       - Write a Brick based building app: tutorial/write_an_app.md
+      - Write a Permission Profile: tutorial/write_a_permission_profile.md

projects/sbos-frontend/config/defaultSettings.ts

@@ -23,6 +23,7 @@ const Settings: ProLayoutProps & {
     // 参见ts声明，demo 见文档，通过token 修改样式
     //https://procomponents.ant.design/components/layout#%E9%80%9A%E8%BF%87-token-%E4%BF%AE%E6%94%B9%E6%A0%B7%E5%BC%8F
   },
+  locale: "en-US",
 };
 
 export default Settings;