BIOME – IOT Application

Functional Specification Document (FSD)

1
 TABLE OF CONTENTS
Acronyms and Abbreviations.................................................................................................................... 3

Document Information .............................................................................................................................. 4

Revision History ........................................................................................................................................... 4

Purpose & Overview .................................................................................................................................. 5

Current Implementation ............................................................................................................................ 5

Desired Implementation . .......................................................................................................................... 5

Out of Scope .............................................................................................................................................. 8

Constraints and Assumptions .................................................................................................................... 8

User Stories: ................................................................................................................................................. 9

User Story 1: Sign In ................................................................................................................................. 9

User Story 2: Forget Password................................................................................................................. 9

User Story 3: Dashboard ....................................................................................................................... 10

User Story 4: Microclimates / Locations ............................................................................................... 10

User Story 5: Location wise Chart ........................................................................................................ 11

User Story 6: Water Management ....................................................................................................... 12

User Story 7: Lighting Management .................................................................................................... 12

User Story 8: Admin Settings ................................................................................................................. 13

User Story 9: User Profile Management ............................................................................................... 14

User Story 10: Location & Device Management ................................................................................ 15

User Story 11: Email Notification Mechanism ...................................................................................... 16

Appendix: System Functional Flow ......................................................................................................... 17

2
Acronyms and Abbreviations

AWS: Amazon Web Services

FSD: Functional Specification Document

IOT: Internet of Things

S3: Simple Storage Service

UAT: User Acceptance Testing

3
Document Information
Prepared By: Tooba Mirza
Issue Date: 05th September, 2019
Reviewed By: Farhan Munir
Approved By: Imran Moinuddin, Collin Stoner
Approval Date: 18th September, 2019
Status: Draft

Revision History
Revision Date Author(s) Description
Number
V1.0 05th Sep, 2019 Tooba Mirza -

4
Purpose & Overview
Biome produces indoor green walls that purify the air and beautify the architectural space. The
machines are self-sufficient, hydroponic plant gardens that host between 10 and 40 plants, an
internal water tank and the proper air and plumbing to keep the plants alive and healthy as they
scrub the air.

To support the device, an onboard controller manages the water and air cycles with a suite of
sensors to detect and adapt to the surrounding environment. Based on the needs of the plants,
more or less light, water and air are applied to the plants.

To track performance and add value to the user, the devices are WiFi enabled and transmit sensor
and health data back to a server where the data can be monitored to improve functionality and
maintain the plants (which are very sensitive to environmental changes

Current Implementation
The current server is implemented in Node.js running on a low tier AWS virtual machine. Time series
data is stored using Influx DB and control/management data is stored in a MongoDB server, hosted
by MongoDB as a service.

The current implementation is scale limited and has nearly reached capacity. Additionally, it lacks
a front end that can be shown to customers. Data is plotted with Grafana for engineering use only.

Once the new scalable system is in place, existing implementation will no longer be applicable.

Desired Implementation
The product of the IOT application development is a Serverless design implemented on AWS, to
allow seamless scale out and an attractive front end for customers to interact with in addition to
the engineering and plant operations team.
 From the backend, a standard Serverless architecture:

5
 o DynamoDB or MongoDB should be used to track all data
o Lambda functions and API Gateways should be used to manage data intake, ideally
implemented in JavaScript
o Cognito should provide authentication for users and super-users (plant operations and
engineering)
o AWS Amplify and S3 would be used to store, build, deploy, and host web application on AWS
 React.js JavaScript library will be used to develop application front end.
 A front-end sketch has been provided to be used as a base to build the front end. A front-end
HTTP and CSS template has been provided to minimize coding of the front-end look and feel

Devices Data & APIs

 Each device will provide sensor and health data at regular intervals, typically every 10-15
seconds. The rate may vary considerably.
 Each device will request commands from the server. Commands may include:
o Updates to device settings (water cycle, fan cycle, light color/timing, etc.)
o Firmware updates
o Resets

Data Collection API

Type POST

Location /device/<device serial>

Takes in sensor and health data on regular intervals from each machine

Data:

Field Detail

Wlvl The current water level in % 0-100

Lux The current ambient light reading (lux, floating point)

Tin The current internal temperature (degrees F)

Tout The current external temperature (degrees F)

Rhin The current internal relative humidity (%)

Rhout The current external relative humidity (%)

Pump The current state of the pump. 0 or 1

Pump_rpm The current RPM of the pump (RPM, numeric)

Fan The current state of the fans. 0 or 1

Wstate The current water state (0-100, floating point)

Wtarget The current water target level (0-100, floating point)

Pump_dry A flag indicating if the pump has detected no water and must be primed by
filling the tank

Returns 200 if data is accepted

6
 Command API

Type GET

Location /device/cmd/<device serial>

Requests the top queued command for the device. Commands are issued onto a FIFO stack. The
top command will remain active until it is confirmed (which pops it off the top of the stack). Until
confirmation, the same command will be returned by this api call.

This call will be made repeatedly by the device on 10-15 second intervals. If a command is
supplied, it will be executed and validated if successfully received. (Execution does not need to
be successful, only receipt). Another GET may be issued rapidly after the previous command is
executed to speedily execute multiple commands.

Data:

Field Detail

Cmd The command type (string)

data The data for the command (string)

Uuid A UUID that may be used to validate and complete the command later

Returns 200 if command data is available. Returns 204 if no command is queued.

Validate Command API

Type POST

Location /device/cmd/<device serial>

Indicates that the device received and executed a command. The command may now be
removed from the queue.

Data:

Field Detail

Uuid The UUID of the command to validate.

Result The result of the command (string). Success/failure/string data for result, etc…

Returns 200 if command data is available. Returns 204 if no command is queued.

Commands & Data:

Commands are provided in the ‘cmd’ field of the command GET function call. The command
indicates the type of operation the device should take. The Data field is used by the device to
complete the operation. Both are strings.

The commands, their functions and associated data are detailed below:

Command Data Operation Description

OTA Relative URL of OTA Device should start an Over-The-Air firmware update. The
package (for data string is the URL of the OTA firmware file, relative to the

7
 example: server base address. The OTA firmware file must be publicly
/version22.firmware) accessible so that the device may download it.

RESET None Resets the device (reboot)

LED {r: <0-255>, g: <0- Sets the color of the LED’s and which LEDs are enabled. R,
255>, b: <0-255>, g, and b are the Red, Green and Blue color values. Left,
left: true/false, right: right, top, bottom are Booleans that indicate if the LED bank
true/false, top: should be displayed or not.
true/false, bottom:
true/false

WATER JSON array of 24 Updates the water target numbers on the device. There is
numbers, 0-100. one setting for each hour of the day (24 numbers total).
Each setting is between 0 and 100.

FAN {period: <integer>, Updates the fan settings on the device.

ontime: <integer>}

Out of Scope
 Any requirement or clause that is not part of this document will be considered out of scope
 Any requirement that has not been made part of Signed off Functional Specification / Scope
document would require Change Management process to initiate, if the effort per requirement
is 5 working hours or more. This change would also demand a respective change in project’s
Scope, Cost and Schedule

Constraints and Assumptions

 Project team would focus more on functionality and less on application outlook. They will use
the Bootstrap Theme provided by Collin to minimize design effort. Application screens do not
have to look as-it-is as they are in the provided wireframes
 If the key stakeholders do not provide feedback or Sign Off on Functional Specification
Document within 10 working days from its circulation, it will automatically be considered
“Approved” from each responsible party
 Project UAT will be performed on the basis of approved Functional Specification Document
 IOT application timeline is 2 months for the scope defined in FSD, starting from Sep, 2019 till the
end of Oct, 2019

8
User Stories:
User Story 1: Sign In
User Interface

Key Functional Points:

 User provides email and password.

 On clicking of “Submit” button, user will be redirected to Landing Page i.e. Dashboard screen
after successful login
 User can cache his email and password for later use by clicking on “Remember Me” check box.

User Story 2: Forget Password

User Interface

9
Key Functional Points:

 In case of unsuccessful Login, user may be redirected to Forget Password screen to reset the
password for a respective account
 User Account with that email address must exist in the system

User Story 3: Dashboard

User Interface

Key Functional Points:

 For this system to be operational, the metric to determine air pressure are temperature, humidity,
lighting and water level. Air Quality and Comfort Level are not being considered for now
 The top left level chart on Dashboard displays the average of all devices for a respective
Company for each metric at a specified time (last 12 hours)
 The top right stats is the average of all devices in the system for a specific metric at the current
time
 The lower table represents the location wise average of devices of a respective Company in
the system for each metric at the current time
 Appropriate symbols will be used to represent metrics

User Story 4: Microclimates / Locations

User Interface

10
Key Functional Points:

 Graphical representation of location wise average of all devices of a respective Company for
each metric (temperature, humidity, lighting and water level ) at the current time

User Story 5: Location wise Chart

User Interface

11
Key Functional Points:

 Chart wise representation of the average of all devices of a respective location for last 12 hours
for each metric (temperature, humidity, lighting and water level)
 This functionality has check boxes to turn on / off a metric wave and date time filters as well
 The stats on top is the average of all devices in the system for each metric at the current time
for that location

User Story 6: Water Management

User Interface

Key Functional Points:

 This feature show the current water level of all devices present in the system at every location
 Taiga is a name given to IOT devices

User Story 7: Lighting Management

User Interface

12
Key Functional Points:

 This feature shows the lighting arrangement at four sides of each device/Taiga
 Lights can also be controlled from here e.g. if we uncheck “Left” of Device 01 from the lighting
panel in the system, the left light of device would turn off.

User Story 8: Admin Settings

User Interface

13
Key Functional Points:

 Personas:
o Super User can access and alter all functionalities in the system.
o Admin users can access and alter those functionalities that belong to the Company he/she
is made part of.
o Non-Admin can only access those screens they have been given permission of
 Super User can add / activate / deactivate companies in the system
 Super User / Admin can add / activate / deactivate users in the system. There will be no hard
delete in the system
 A user can belong to only one Company in the system
 There will be an admin web panel / command line interface to send a firmware update
command, reset command to a device and machine settings update (send new water target,
send new fan settings, etc.)
Note: Commands will always be generated by some triggering mechanism like on/off light
switches, reset of devices etc. There will be no scheduled mechanism to deal with commands.

User Story 9: User Profile Management

User Interface

Key Functional Points:

14
 User can update personal Information like First Name, Last Name etc. However, a user cannot
update his Company and Email address once his account is created
 User can also change Password through this feature. Default password for all users on account
creation is Apple123!@#

User Story 10: Location & Device Management

User Interface

Key Functional Points:

 Super User / Admin can add / activate / deactivate locations and devices in the system of their
respective companies. There will be no hard delete in the system
 Super User / Admin can assign devices to specific locations
 A company can have one or many locations. A location can have one or many devices
 If a company is deactivated, all locations, users and devices associated with it will automatically
be deactivated in the system. If a location is deactivated, all devices connected to that
location will automatically be deactivated in the system

15
User Story 11: Email Notification Mechanism
User Interface

Key Functional Points:

 User would get notified if water level of a device reaches a certain level below threshold as
shown in the above wireframe
 For this system, any other threshold settings except water level is not required to maintain

16
Appendix: System Functional Flow

17