# Complete list of jobs

## System Overview

System overview expressed as an Entity Relationship Diagram. Note the markings on the connecting lines designate [how many of that type of entity are allowed to exist](https://mermaid-js.github.io/mermaid/#/entityRelationshipDiagram) (e.g. `||` means exactly one, and `o{` means zero or more).

erDiagram
	App }o--|| Gateway : bluetooth
    App }o--|| Router: Wifi
	PC }o--|| Router : Ethernet		
	PC }o--|| Router : Wifi
    Gateway }o--|| Router: Wifi
    Gateway }o--|| Router: Ethernet
	PC }o--|| Gateway : USB	
    Cloud ||--o{ Gateway : MQTT
    Gateway ||--o{ BMS : canbus-1
    Gateway ||--o{ Inverter : modbus-master
    Gateway ||--o{ Inverter : modbus-worker
    Gateway ||--o{ Inverter : canbus-2
    
    Cloud ||--o{ App : API
    Cloud ||--o{ PC : API

## Gateway

### Gateway supports all commands over any input method

Any supported command can come in from any input source. For example, a request to write a canbus frame can come from a PC connected over USB. Or a request to read a sunspec register can come from the App over bluetooth.

### Gateway supports sunspec

The gateway must support the sunspec models

- 802 - battery bank
- 803 - lithium bank with string-level repeating block
- 805 - lithium module with cell-level repeating block

Read must be supported for all points.

Write must be supported for all applicable points.

Implementation must be sunspec compliant. E.g. unimplemented values must be noted per the spec.

At a minimum, the mandatory points must be supported. Other non-mandatory points can be supported as desired.

### Gateway support AWS IoT

The gateway must connect to the AWS IoT service and maintain its state with a device shadow and periodic updates.

### Gateway has all necessary device drivers

In order to support all sunspec registers, the gateway will combine data from the inverter and BMS. Therefore, the gateway must communicate with

- All supported Fortress BMS over canbus
- All supported inverters over modbus or canbus. Communication method may vary by inverter make/model.

### Gateway can update own firmware

The gateway firmware version can be updated from these data sources:

- MQTT
- USB

sequenceDiagram

Input->>Gateway: Update gateway firmware to <version> from <source>
Gateway->>Gateway: Checks version is different from current
Gateway->>Data Source: Request for new firmware
Data Source->>Gateway: Sends new version
Gateway->>Gateway: Data integrety check
Gateway->>Gateway: Loads new version
Gateway->>Gateway: Restart
Gateway->>Gateway: Start-up tests
alt new version works
Gateway->>Input: Success message with new version number
else new version fails
Gateway->>Gateway: Rolls back to previous version
Gateway->>Input: Failure message with existing version number
end

### Gateway can update BMS firmware

The gateway can update the BMS firmware to a different version. BMS firmware is updated over CANBUS.

### Gateway can discover connected Products

The gateway can automatically discover which inverters and Fortress batteries are connected. A manual discovery process must also be supported for when automatic discovery fails. In manual discovery a user enters

- product id
- communication port (canbus or modbus)
- baud rate
- config items (e.g. parity, stop bit, etc)

and the gateway will use that information to connect to an attached product.

### Gateway accepts arbitrary canbus frames as input commands

The gateway must support an arbitrary canbus frame as an input command. The response must be the reponse to the command.

### Gateway accepts arbitrary modbus requests input commands

The gateway must support an arbitrary modbus frame as an input command. The response must be the reponse to the command.

### Gateway must implement battery charging strategy

The rate at which the batteries charge is a function of many parameters such as voltage and temperature. Implementing this algorithm at the BMS level is challenging because of the number of different combinations of inverter and BMS that are possible. Instead, the gateway must implement this closed-loop communication by sitting between the BMS and the inverter (see System Architecture above).

### Input Commands

The details of these functions, and all their arguments, are still TBD.

- Firmware
- Gateway
- Update. Update the firmware to <version number>.
- Response: response code and version number
- get version. Returns the current running version number
- BMS
- Update. Update the firmware to <version number>.
- Response: response code and version number
- get version. Returns the current running version number
- Serial
- CAN frame. Send <message> to the CANBUS on <port>
- Response: Response frame from the canbus.
- Modbus command. Perform modbus <function code> using <data> to the modbus on <port>
- Response: Modbus response
- Discovery
- Automatic. Trigger the gateway's autodiscovery method
- Response: List of discovered equipment
- Manual. Force connection to the device on <port> using <serial configs>.
- Response: response code
- Telemetry
- Send. Force the gateway to send data about its current state
- Response: response code
- State. The state includes the full sunspec implementation (see below) as well as any other set-up parameters. e.g. baud rate, wifi connection information, update frequency, etc.
- Get. Get the current state. Optionally, get some subset of the state.
- Response: requested state information
- Update. Update the value of <state path> to <value>.
- Response: response code.

## App

The consumer smart phone application must do the following jobs

### App must discover gateways

The app can automatically discover gateways that are

- nearby using bluetooth
- on the same LAN

In addition, the app will accept manual discovery of gateways with the appropriate inputs (e.g. ip address on the LAN).

### App allows new customers to register

App must have a flow to allow users to enter their information to create a new account on the system. Users can also edit their existing registration.

### App allows customers to register new products

Once connected to a gateway, the app must have a flow that

- retrieves an equipment list from the gateway
- gateway's automatic discovery function
- gateway's manual discovery function if not all equipment was autodiscovered
- allows user to input current site information
- Uses phone location
- Allows for manual location input
- associates the equipment with the site

### App shows current state of battery bank

App must display some information about the current state of the battery bank. App must support retrieving this data either from

- cloud API
- directly from the gateway via bluetooth
- directly from the gateway via LAN

### App shows historical performance of battery bank

App must display historical information on the performance of the battery bank. This data will be retrieved from the cloud API.

App alerts users to
- device faults
- charging or discharging above a threshold power
- soc below a certain threshold %

### App can change some configuration items
A subset of the config entries can be edited on the app. The list of these items is TBD.

### App can trigger gateway's "update firmware" Input Command

App must support sending this function request either via the cloud API, or directly to the gateway when connected with bluetooth or LAN.

### App can trigger gateway's "send telemetry" Input Command

App must support sending this function request either via the cloud API, or directly to the gateway when connected with bluetooth or LAN.

### App can easily open a support ticket

The app must allow a user to get tech support over

- phone call
- email

without filling out a lengthy form. If the user requests support the support ticket should be created and populated automatically with links to that user's equipment records and historical data. There must be an optional "additional comments" field that will allow the user to elaborate on the problem they are experiencing. There must also be a drop-down menu pre-populated with common tech support reasons.

## Web Portal

### Web Portal must support sending gateway any of the supported Input Commands

The web portal is meant for admin use. All of the gateway's Input Commands must be accessible via the web portal.

### Web Portal shows historical performance of battery bank

Web Portal must display historical information on the performance of the battery bank. This data will be retrieved from the cloud API.

###

# V2

This section documents features planned for the future, that should not be implemented in the first version.

## Gateway must implement Rapid Shutdown

An emergency power off (EPO also called rapid shut down) is a safety measure that can quickly stop AC power from an inverter.

The gateway must detect a dry contact and send a shutdown command to the BMS.

## Gateway supports inverter control functions

In addition to the sunspec, the gateway should expose any control functions on the inverter. The control functions will vary by the make/model of the inverter and the inverter operating state.

For example:

graph TB
A(Inverter) --> Sleep
A --> Starting
A --> Self-consumption
A --> Off-grid
A --> freeop[Discharge Setpoint]

freeop --> chg[Set Charge Power]
freeop --> dischg[Set Disharge Power]

## Gateway and Cloud integrate with Home Assistant

The gateway should use Project Matter to integrate with the home assistant ecosystem. Cloud system should use the appropriate home assistant apis. Details TBD.

## Sunspec modbus is available on a modbus port
A sunspec-compliant modbus implementation must be available over modbus-RTU using one of the RS-485 ports