Add images to repo

EnAccess · May 31, 2023 · d570fcb · d570fcb
1 parent 16f04fa
commit d570fcb
Show file tree

Hide file tree

Showing 14 changed files with 109 additions and 96 deletions.
diff --git a/docs/assets/backend/access-token.png b/docs/assets/backend/access-token.png
diff --git a/docs/assets/backend/adding-widget.png b/docs/assets/backend/adding-widget.png
diff --git a/docs/assets/backend/assets-page.png b/docs/assets/backend/assets-page.png
diff --git a/docs/assets/backend/creating-devices.png b/docs/assets/backend/creating-devices.png
diff --git a/docs/assets/backend/creating-meter-id.png b/docs/assets/backend/creating-meter-id.png
diff --git a/docs/assets/backend/creating-relations.png b/docs/assets/backend/creating-relations.png
diff --git a/docs/assets/backend/dashboard-with-widget.png b/docs/assets/backend/dashboard-with-widget.png
diff --git a/docs/assets/backend/entering-details-in-assests-page.png b/docs/assets/backend/entering-details-in-assests-page.png
diff --git a/docs/assets/backend/paystack-landing-page.png b/docs/assets/backend/paystack-landing-page.png
diff --git a/docs/assets/backend/setting-up-dashboards-2.png b/docs/assets/backend/setting-up-dashboards-2.png
diff --git a/docs/assets/backend/setting-up-dashboards.png b/docs/assets/backend/setting-up-dashboards.png
diff --git a/docs/assets/backend/thingsboard-dashboard.png b/docs/assets/backend/thingsboard-dashboard.png
diff --git a/docs/backend/api-documentation.md b/docs/backend/api-documentation.md
@@ -1,194 +1,202 @@
+# API Documentation
+
 This documents contains API guide for setting up Thingsboard web interface connecting to Paystack and database backend
 
-# Introduction
+## Introduction
 
 This document provides details on how to integrate Thingsboard API to developers metering application to view historic energy and to implement the designed web for top-up via Paystack, checking meter connectivity status, STS-token generation, set tariff per kWh and details to database.
 
-# Definitions
+## Definitions
 
 **Developer:** is referred to in this document as the web developer or meter manufacturing entity.
 
 **User:** is referred to in this document as the metering customer.
 
-# Thingsboard API integration:
+## Thingsboard API integration:
 
 Thingsboard is an open-source server-side platform that allows you to monitor and control IOT devices. It is free for both personal and commercial use and can be deployed anywhere. Steps to set up a things board page is highlighted below:
 
-## Step 1: Signing up for Thingsboard
+### Step 1: Signing up for Thingsboard
 
 The first step requires first time developer to setup a things board account by signing up using the [https://demo.thingsboard.io/login](https://demo.thingsboard.io/login) link, once this is done, the developer can sign in using the login details provided while signing up.
 
 If the developer is on the right page, the developer should end up with the page highlighted below.
 
-![image](https://github.com/EnAccess/OpenSmartMeter/assets/14202480/bd480b10-a714-4b9f-aeb3-de22d15df147)
-
-_Figure 1: Thingsboard dashboard_
-
+<figure markdown>
+  ![Thingsboard dashboard](../assets/backend/thingsboard-dashboard.png)
+  <figcaption>Thingsboard dashboard</figcaption>
+</figure>
 
-## Step 2: Setting up Thingsboard page
+### Step 2: Setting up Thingsboard page
 
 Developer needs to setup the Thingsboard to view meter parameters such as energy and top-up balance. To do this, developer need to navigate to the asset's icon on the left side of the web page, click on it and locate the add asset button on the top right corner of the page. A sample of add icon picture and assets page is shown below.
 
-![image](https://github.com/EnAccess/OpenSmartMeter/assets/14202480/ba84e967-9b62-4282-8e5c-d8cb577e3e4d)
-
-_Figure 2: Assets page_
-
+<figure markdown>
+  ![Assets page](../assets/backend/assets-page.png)
+  <figcaption>Assets page</figcaption>
+</figure>
 
-## Step 3: Add Asset
+### Step 3: Add Asset
 
 Once developer clicks on "Add Assets", user will end up with the page shown below. Developer can proceed to fill **Name, Assets type, Label, Customer**. However, the most important is name and asset type. Once the information is filled, user can proceed to click the add button and the name will show up in the assets page.
 
-![image](https://github.com/EnAccess/OpenSmartMeter/assets/14202480/b90355ef-1025-4fc9-94e2-996388c25c8f)
+<figure markdown>
+  ![Entering details in Asset Page](../assets/backend/entering-details-in-assests-page.png)
+  <figcaption>Entering details in Asset Page</figcaption>
+</figure>
 
-_Figure 3: Entering details in Asset Page_
-
-
-## Step 4: Add Devices
+### Step 4: Add Devices
 
 Once developer is done setting up the assets, user can proceed to click on the devices button and add devices. Image of the add process is shown below, in our case we added "credit" and "energy".
 
-![image](https://github.com/EnAccess/OpenSmartMeter/assets/14202480/b5e69e71-e3a1-4cf7-91df-90ff2fb851fe)
-
-_Figure 4: Creating Devices_
-
+<figure markdown>
+  ![Creating Devices](../assets/backend/creating-devices.png)
+  <figcaption>Creating Devices</figcaption>
+</figure>
 
-## Step 5: Create relations between assets and devices
+### Step 5: Create relations between assets and devices
 
 Developer must create a relation between assets and devices by clicking on the assets button and navigating to the asset previously created in step 3. developer can add relation by navigating to relations and select the entity type as devices then entity name as the name created under devices. If all is done correctly, user should end up with the highlighted page below.
 
-![image](https://github.com/EnAccess/OpenSmartMeter/assets/14202480/e1fed66e-adfb-4202-89ff-4c318fd933d5)
+<figure markdown>
+  ![Creating Relations](../assets/backend/creating-relations.png)
+  <figcaption>Creating Relations</figcaption>
+</figure>
 
-_Figure 5: Creating Relations_
+### Step 6: Access Token
 
+To enable the meter send parameters to the Thingsboard API, developer will need to navigate to devices, click on the created devices and copy the access token of each created devices by navigating to the copy access token icon. The two copied token is pasted on the declared variable for `TOKEN` and `TOKEN1` on the firmware code.
 
-## Step 6: Access Token
+The page to copy the access token looks like picture pasted below.
 
-To enable the meter send parameters to the Thingsboard API, developer will need to navigate to devices, click on the created devices and copy the access token of each created devices by navigating to the copy access token icon. The two copied token is pasted on the declared variable for TOKEN and TOKEN1 on the firmware code. The page to copy the access token looks like picture pasted below.
+<figure markdown>
+  ![Access Token](../assets/backend/access-token.png)
+  <figcaption>Access Token</figcaption>
+</figure>
 
-![image](https://github.com/EnAccess/OpenSmartMeter/assets/14202480/5d5dbd0c-e2f1-4113-a0a6-84c949483b4e)
-
-_Figure 6: Access Token_
-
-
-## Step 7: Creating Dashboard
+### Step 7: Creating Dashboard
 
 Developer is required to create dashboard to visualize sent information from the meter in forms like graph, charts, and lots more as desired by the developer.To create a dashboard to view meter parameters, user will need to navigate and click on the Dashboards icon on theThingsboard page, click the _add icon_ to create a dashboard and proceed to fill the necessary details shown on the page.
 
 Next developer clicks to _add entity_ aliases and fill the required details. User should end up with the below screen if all is done correctly.
 
-![image](https://github.com/EnAccess/OpenSmartMeter/assets/14202480/d3b81e24-3e9e-41c3-bacd-3f574d36943c)
-
-_Figure 7: Setting up Dashboards_
+<figure markdown>
+  ![Setting up Dashboards](../assets/backend/setting-up-dashboards.png)
+  <figcaption>Setting up Dashboards</figcaption>
+</figure>
 
-![image](https://github.com/EnAccess/OpenSmartMeter/assets/14202480/e3693106-6fbc-4315-a873-61581897c626)
+<figure markdown>
+  ![Setting up Dashboards II](../assets/backend/setting-up-dashboards-2.png)
+  <figcaption>Setting up Dashboards II</figcaption>
+</figure>
 
-_Figure 8: Setting up Dashboard II_
-
-
-## Step 8: Add Widget
+### Step 8: Add Widget
 
 Under dashboard, developer will navigate and click on _ADD NEW WIDGET_, then fill the necessary parameters as created. If all is properly filled, developer should end up with the below screen.
 
-![image](https://github.com/EnAccess/OpenSmartMeter/assets/14202480/c925c54f-fea0-454f-ba2e-99cf55829aa6)
-
-_Figure 9: Adding Widget_
-
-![image](https://github.com/EnAccess/OpenSmartMeter/assets/14202480/0b839ad6-60bd-43ba-b620-484fbc602448)
+<figure markdown>
+  ![Adding Widget](../assets/backend/adding-widget.png)
+  <figcaption>Adding Widget</figcaption>
+</figure>
 
-_Figure 10: Dashboard with Widget_
+<figure markdown>
+  ![Dashboard with Widget](../assets/backend/dashboard-with-widget.png)
+  <figcaption>Dashboard with Widget</figcaption>
+</figure>
 
-Note: Developer can add different widget as desired.
+!!! note
 
-1.
-# Paystack Integration:
+    Developer can add different widget as desired.
 
+## Paystack Integration:
 
-## Step 1: Creating a Paystack Account
+### Step 1: Creating a Paystack Account
 
 Developer will begin by creating a Paystack account using [https://dashboard.paystack.co/#/signup](https://dashboard.paystack.co/#/signup) link to sign up, after the necessary details is filled and user has successfully signed up, the user will be redirected to his/her dashboard. If the account is created successfully, user should end up with the page below.
 
-![image](https://github.com/EnAccess/OpenSmartMeter/assets/14202480/21fcc04d-0ba0-479d-aa05-2061df8a0a41)
+<figure markdown>
+  ![Paystack Landing page](../assets/backend/paystack-landing-page.png)
+  <figcaption>Paystack Landing page</figcaption>
+</figure>
 
-_Figure 11: Paystack Landing page_
-
-
-## Step 2: Copy and replace public key
+### Step 2: Copy and replace public key
 
 Developer need to login to the Paystack account and navigate to settings, [API keys & webhooks](https://dashboard.paystack.com/#/settings/developer), then copy the test public key and put in _initialize.php_ code under the web software. The public key to be replaced looks like the below.
 
-![image](https://github.com/EnAccess/OpenSmartMeter/assets/14202480/c429bfca-4d23-45ef-8a9b-5680d179bf80)
+```php-inline
+CURLOPT_HTTPHEADER => [
+  "authorization: Bearer sk_test_5a679ebeb2769a355091ac05f843d7187b0e7b0e", //replace this with your own test key
+  "content-type: application/json",
+  "cache-control: no-cache"
+],
+```
 
 Once this is done, all transaction done on the webpage will be paid to the developers demo account, the public key and Paystack account setup is a demo version, to receive real payment into live account, developer needs to submit compliance form and go live by navigating to settings, accounts and fill/upload the necessary document to take account live and receive live payments.
 
-1.
-# Database & Backend
-
+## Database & Backend
 
-## Setting up each meter and assigning meter number:
+### Setting up each meter and assigning meter number:
 
 Each meter is setup by firstly creating a database with same name in the file named subscribe.php under the web software folder. The database servername, dbname, username, password must be edited to same name as used in the database creation. A sample image is shown below.
 
-<img width="288" alt="image" src="https://github.com/EnAccess/OpenSmartMeter/assets/14202480/843a0104-2a13-400c-ad42-a8511cebfea8">
-
-_Figure 12: Database Creation_
+```php-inline
+$servername = "localhost";
+$dbname = "id17130795_energymeter";
+$username = "id17130795_byker";
+$password = "Danielkomolafe00%";
+```
 
 After the database is setup and the developer has changed all necessary parameters in the subscribe.php, the developer will need to create a table named meter with four rows as named below :
 
-1. **meterid :**
-
-The meter id row holds the assigned meter number.
-
-1. **amount :**
-
-The amount row holds the amount topped up by user.
-
-1. **transaction\_id :**
-
-The transaction\_id row holds the transaction id sent by Paystack.
-
-1. **status : t** he status row holds the status of each transaction if successful or failure.
+1. **meterid :** The meter id row holds the assigned meter number.
+2. **amount :** The amount row holds the amount topped up by user.
+3. **transaction\_id :** The transaction\_id row holds the transaction id sent by Paystack.
+4. **status :** he status row holds the status of each transaction if successful or failure.
 
 After this is done, the developer can assign meter number to all designed meters by navigating to the database and add desired meter number. Meter number can be from 1 to 99,000. Each meter number can have any prefix as desired by user, sample of different created and assigned meter is shown below in the meterid row.
 
-![image](https://github.com/EnAccess/OpenSmartMeter/assets/14202480/d7f510f5-0ec2-42df-a840-1238a30558e2)
-
-_Figure 13: Creating Meter ID_
+<figure markdown>
+  ![Creating Meter ID](../assets/backend/creating-meter-id.png)
+  <figcaption>Creating Meter ID</figcaption>
+</figure>
 
-
-## Setting Tariff:
+### Setting Tariff:
 
 The tariff is set by navigating to the file named subscribe.php under the web software folder, the developer needs to locate the variable named tariff and change the value from 70 to the desired tariff, and automatically the meter will fetch the tariff in the 12th hour as designed in the firmware code.
 
-<img width="174" alt="image" src="https://github.com/EnAccess/OpenSmartMeter/assets/14202480/d4eb4a53-ba37-4718-bee0-8ebae31c05e3">
-
+```php-inline
+$tarrif = "70";
+```
 
-
-## STS Token Generation:
+### STS Token Generation:
 
 The STS token generation is automatic once the developer assign a meter number between 1 and 99000, the meter number assigning can have any prefix as desired by developer, though in the sample code created, the prefix is set to be any two letters, if developers change the prefix before the meter number, user has to change the code below from 2 to the new number of suffix. The code is available in check.php inside the web software folder.
 
-![image](https://github.com/EnAccess/OpenSmartMeter/assets/14202480/0db756cc-36fd-44c3-96f3-01fcffe67fa2)
+```php-inline
+$mt_no = substr($MT,2, 10); //to extract the digit out of the meter code number
+```
 
 Once the meter number is properly assigned and setup, the meter number is automatically generated.
 
-
-## Private key:
+### Private key:
 
 To further encrypt the STS token generation algorithm, a private key was used to bind the token with the firmware code. The private key can be a value between 100 and 111 and is changeable under check.php in the web software folder, the image of the line to be changed is shown below.
 
-![image](https://github.com/EnAccess/OpenSmartMeter/assets/14202480/7ecee412-a6cb-4110-8e0a-76e569ac8d39)
+```php-inline
+$privatekey = 109;  // can be a number between 100 and 111
+```
 
 **Note:** the private key used on the web code must be same as the private key used in the firmware code.
 
-
-## API encryption:
+### API encryption:
 
 The web platform is encrypted such that a meter can send or receive information from a webpage expect the API key used on the web page is same as the API key used on the firmware. The API key is changeable as desired in the subscribe.php under web software. The image is shown below.
 
-<img width="297" alt="image" src="https://github.com/EnAccess/OpenSmartMeter/assets/14202480/f7dbd7f2-e193-4625-9d0b-72764fbfa58e">
-
+```php
+$api_key_value = "tPmAT5Ab3j7F9";
+```
 
-## Function of each folder in the web API
+### Function of each folder in the web API
 
 All folders in the web interface is named below:
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -72,6 +72,11 @@ markdown_extensions:
       anchor_linenums: true
       line_spans: __span
       pygments_lang_class: true
+      extend_pygments_lang:
+        - name: php-inline
+          lang: php
+          options:
+            startinline: true
   - pymdownx.inlinehilite
   - pymdownx.keys
   - pymdownx.magiclink: