On a new install, the resetdb utility needs to be run to initialize the database tables. For existing installations, it will wipe all user data.
Run the resetdb utility, and confirm with y:
ubuntu@ubuntu:~/greenbus-3.0.0$ bin/greenbus resetdb
Proceed with modifications? (y/N)
y
ubuntu@ubuntu:~/greenbus-3.0.0$The first background process to start is the GreenBus services, which provide the core service APIs to the state of the system. Processes are started using the bin/greenbus script and specifying the process name:
ubuntu@ubuntu:~/greenbus-3.0.0$ bin/greenbus services start
Starting services...
19160To verify that the services have started, we can check the log file:
ubuntu@ubuntu:~/greenbus-3.0.0$ tail var/log/services/services.log
13:46:44.739 [services-akka.actor.default-dispatcher-2] INFO akka.event.slf4j.Slf4jLogger - Slf4jLogger started
13:46:44.920 [IoReceiver - /127.0.0.1:5672] INFO o.a.q.c.s.DynamicSaslRegistrar - Additional SASL providers successfully registered.
13:46:44.922 [IoReceiver - /127.0.0.1:5672] INFO o.a.q.c.s.CallbackHandlerRegistry - Callback handlers available for SASL mechanisms: [EXTERNAL, GSSAPI, SCRAM-SHA-256, SCRAM-SHA-1, CRAM-MD5-HASHED, CRAM-MD5, PLAIN, AMQPLAIN, ANONYMOUS]
13:46:44.993 [services-akka.actor.default-dispatcher-5] INFO io.greenbus.sql.postgres.Connector - Initializing postgres connection pool: core@jdbc:postgresql://127.0.0.1:5432/greenbus3_d
13:46:45.193 [services-akka.actor.default-dispatcher-5] INFO io.greenbus.services.CoreServices$ - Binding services
13:46:45.393 [services-akka.actor.default-dispatcher-5] INFO io.greenbus.services.CoreServices$ - Services boundLog files for various processes and utilities can be found in var/log/[process]/[process].log
The GreenBus command-line interface (CLI) provides terminal access to the GreenBus services. To run it we use the cli utility in the GreenBus distribution:
ubuntu@ubuntu:~/greenbus-3.0.0$ bin/greenbus cli
_____ ____
/ ____| | _ \
| | __ _ __ ___ ___ _ __ | |_) |_ _ ___
| | |_ | '__/ _ \/ _ \ '_ \| _ <| | | / __|
| |__| | | | __/ __/ | | | |_) | |_| \__ \
\_____|_| \___|\___|_| |_|____/ \__,_|___/
GreenBus Platform (3.0.0)
Dedicated to enabling the smart grid.
Green Energy Corp (www.greenenergycorp.com)
Hit '<tab>' for a list of available commands
and 'help [cmd]' for help on a specific command.
Hit '<ctrl-c>' to close console.
Attempting auto-login for user system.
system@127.0.0.1>While the CLI is connected to the services through AMQP, with no model loaded most commands return empty results:
system@127.0.0.1> entity:list
system@127.0.0.1>The samples/ directory in the distribution contains a sample model in the GreenBus XML import/export format. To load it into the system, use the import utility by providing it the path to the file:
ubuntu@ubuntu:~/greenbus-3.0.0$ bin/greenbus import samples/model/config.xml
[...]
Proceed with modifications? (y/N)
y
== Progress:
.......
== Finished in 1245 ms
ubuntu@ubuntu:~/greenbus-3.0.0$The importer lists the modifications to the system model loading the XML file will cause. In this case the model is empty and all objects are being added.
The GreenBus CLI now shows the objects present in the system:
system@127.0.0.1> entity:list
Name Types
-----------------------------------------------------------------
Calculations | (Endpoint)
MGSite | (EquipmentGroup, MicroGrid, Root)
MGSite.PCC_cbr_cust | (CustomerBreaker, Equipment, PCC)
MGSite.PCC_cbr_cust.Amps | (PCCCurrent, Point)
MGSite.PCC_cbr_cust.Close | (BreakerClose, Command)
MGSite.PCC_cbr_cust.Hz | (FreqSource, Frequency, Point)
MGSite.PCC_cbr_cust.kV | (PCCVoltage, Point)
MGSite.PCC_cbr_cust.kW | (DemandPower, Point)
MGSite.PCC_cbr_cust.PwrFact | (Point, PowerFactor)
MGSite.PCC_cbr_cust.Status | (BreakerStatus, Point)
MGSite.PCC_cbr_cust.Trip | (BreakerTrip, Command)
MGSite.RoofPV | (Equipment, Generation, PV)
MGSite.RoofPV.%_cap | (PercentCapacity, Point)
MGSite.RoofPV.Disable | (BreakerTrip, Command)
MGSite.RoofPV.Enable | (BreakerClose, Command)
MGSite.RoofPV.kW_cap | (Point, PowerCapacity)
MGSite.RoofPV.kW_tot | (OutputPower, Point)
MGSite.RoofPV.Status | (PVStatus, Point)
PCC_DNP3 | (Endpoint)
Simulated_PV | (Endpoint)
system@127.0.0.1>Currently only the (stateless) services are running, and while the system model is populated, no data is present because there are no connections to data sources.
To see the data sources defined by the sample model, use the CLI to list the Endpoints:
system@127.0.0.1> endpoint:list
Name Status Last Status Protocol Disabled Types
-----------------------------------------------------------------------------------
Calculations | -- | -- | calculator | false | (Endpoint)
PCC_DNP3 | -- | -- | dnp3 | false | (Endpoint)
Simulated_PV | -- | -- | simulator | false | (Endpoint)
system@127.0.0.1>The "Simulated_PV" Endpoint is defined to use the simulator protocol, which is implemented by a front end processor/protocol adapter included in the distribution.
First, to bring data into the system the measurement processor needs to be running. The measurement processor accepts registrations and handles measurement batches from protocol front ends regardless of their protocol (so the dnp3 and calculator listed above might use the same processor service). To start it, run the processing GreenBus process:
ubuntu@ubuntu:~/greenbus-3.0.0$ bin/greenbus processing start
Starting processing...
19410
ubuntu@ubuntu:~/greenbus-3.0.0$Then start the simulator process to run the simulator protocol front end:
ubuntu@ubuntu:~/greenbus-3.0.0$ bin/greenbus simulator start
Starting simulator...
19468
ubuntu@ubuntu:~/greenbus-3.0.0$With the process up and running, the meas:list command in the CLI can be used to see the current values of Points in the system:
system@127.0.0.1> meas:list
Name Value Type Unit Q Time Off
-------------------------------------------------------------------------------------------------------------
MGSite.PCC_cbr_cust.Amps | -- | -- | -- | -- | -- | --
MGSite.PCC_cbr_cust.Hz | -- | -- | -- | -- | -- | --
MGSite.PCC_cbr_cust.kV | -- | -- | -- | -- | -- | --
MGSite.PCC_cbr_cust.kW | -- | -- | -- | -- | -- | --
MGSite.PCC_cbr_cust.PwrFact | -- | -- | -- | -- | -- | --
MGSite.PCC_cbr_cust.Status | -- | -- | -- | -- | -- | --
MGSite.RoofPV.%_cap | -- | -- | -- | -- | -- | --
MGSite.RoofPV.kW_cap | 200.000 | Analog | kW | | Mon Feb 15 13:52:55 EST 2016 | --
MGSite.RoofPV.kW_tot | 99.161 | Analog | kW | | Mon Feb 15 13:53:37 EST 2016 | --
MGSite.RoofPV.Status | OPEN | String | status | | Mon Feb 15 13:53:29 EST 2016 | --
system@127.0.0.1>Note that only values associated with the "Simulated_PV" Endpoint have current values.
In the sample, the simulator is configured to publish values with some noise to demonstrate measurement flow. To see values as they arrive in the system, the CLI can subscribe to measurement updates:
system@127.0.0.1> meas:subscribe --all
MGSite.RoofPV.kW_tot | 98.193 | Analog | -- | | Mon Feb 15 13:54:36 EST 2016 | --
MGSite.RoofPV.Status | OPEN | String | -- | | Mon Feb 15 13:54:36 EST 2016 | --
MGSite.RoofPV.kW_tot | 97.856 | Analog | -- | | Mon Feb 15 13:54:38 EST 2016 | --
MGSite.RoofPV.Status | CLOSED | String | -- | | Mon Feb 15 13:54:38 EST 2016 | --
MGSite.RoofPV.kW_tot | 98.062 | Analog | -- | | Mon Feb 15 13:54:42 EST 2016 | --
MGSite.RoofPV.kW_tot | 98.176 | Analog | -- | | Mon Feb 15 13:54:44 EST 2016 | --
system@127.0.0.1>Despite the sample model being an XML format, the GreenBus system model lives in the database and is accessed by the GreenBus API services. The XML loader uses the same APIs available to all developers in order to create, update, or delete model elements.
In order to make modifications to the model through the XML format, first the current state of the model should be exported using the export utility:
ubuntu@ubuntu:~/greenbus-3.0.0$ bin/greenbus export --root MGSite -k -d mgsite_export/
ubuntu@ubuntu:~/greenbus-3.0.0$ ls mgsite_export/
config.xml PCC_DNP3.protocolConfig Simulated_PV.protocolConfig
ubuntu@ubuntu:~/greenbus-3.0.0$The command takes the root element of a fragment of the model (here, "MGSite"), writes opaque key values to files, and puts all results in the mgsite_export/ directory, as shown above.
The config.xml file looks like this:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<configuration xmlns="xml.ldr.greenbus.io">
<equipmentModel>
<equipment name="MGSite" uuid="03cdee65-634c-49b9-8e8d-e06c6cd72116">
<type name="EquipmentGroup"/>
<type name="MicroGrid"/>
<type name="Root"/>
<equipment name="MGSite.PCC_cbr_cust" uuid="f0e5ba66-2966-4641-88d3-7b4908d6ce40">
<type name="CustomerBreaker"/>
<type name="Equipment"/>
<type name="PCC"/>
<analog name="MGSite.PCC_cbr_cust.Amps" unit="A" uuid="7662c786-46b2-47e1-8917-a0ae80e52e1d">
<type name="PCCCurrent"/>
<type name="Point"/>
<triggers>
<filter>
<suppress activation="LOW"/>
</filter>
</triggers>
</analog>
...Note that uuid attributes are now present that were not specified in the source file, samples/model/config.xml. When created, the services assigned unique identifiers. When re-imported, any name changes are correlated to the original object by this UUID.
To modify the model, change the name and unit of the "MGSite.PCC_cbr_cust.Amps" Point like so:
<analog name="MGSite.PCC_cbr_cust.Current" unit="kA" uuid="7662c786-46b2-47e1-8917-a0ae80e52e1d">
...Note that the UUID has been left the same.
The "MGSite.PCC_cbr_cust.Amps" Point is also referenced in the communications model, towards the end of the file:
<endpoint name="PCC_DNP3" uuid="b310356a-679a-489a-8fb1-d34c77771820" protocol="dnp3">
<type name="Endpoint"/>
<keyValue key="protocolConfig" fileName="PCC_DNP3.protocolConfig"/>
<source uuid="7662c786-46b2-47e1-8917-a0ae80e52e1d" name="MGSite.PCC_cbr_cust.Amps"/>
...Change this source reference as well:
<source uuid="7662c786-46b2-47e1-8917-a0ae80e52e1d" name="MGSite.PCC_cbr_cust.Current"/>With these changes made, the updates can be effected in the system be re-importing the configuration:
ubuntu@ubuntu:~/greenbus-3.0.0$ bin/greenbus import mgsite_export/config.xml
Modified points:
MGSite.PCC_cbr_cust.Amps
Name change: MGSite.PCC_cbr_cust.Amps -> MGSite.PCC_cbr_cust.Current
Unit change: A -> kA
Proceed with modifications? (y/N)
y
== Progress:
.
== Finished in 150 ms
ubuntu@ubuntu:~/greenbus-3.0.0$The importer compares the current running system to the state of the XML document, and lists any modifications to be made.
After the update, the modification can be verified with the CLI:
system@127.0.0.1> point:list
Name Category Unit Types
---------------------------------------------------------------------------------------
MGSite.PCC_cbr_cust.Current | ANALOG | kA | (PCCCurrent, Point)
MGSite.PCC_cbr_cust.Hz | ANALOG | Hz | (FreqSource, Frequency, Point)
MGSite.PCC_cbr_cust.kV | ANALOG | kV | (PCCVoltage, Point)The event configuration specifies the set of event types recognized by the system. The configuration can be modified by first exporting the current state to the event configuration XML format:
ubuntu@ubuntu:~/greenbus-3.0.0$ bin/greenbus event-export -d mgsite_events
ubuntu@ubuntu:~/greenbus-3.0.0$ ls mgsite_events/
event-config.xml
ubuntu@ubuntu:~/greenbus-3.0.0$Which produces a file with all event types represented by eventConfig elements:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<events xmlns="events.xml.ldr.greenbus.io">
<eventConfigs>
<eventConfig eventType="System.ControlIssued" severity="3" designation="EVENT" initialAlarmState="UNACK_SILENT">Executed control {command}</eventConfig>
<eventConfig eventType="System.EndpointDisabled" severity="3" designation="EVENT" initialAlarmState="UNACK_SILENT">Endpoint {name} disabled</eventConfig>
<eventConfig eventType="System.EndpointEnabled" severity="3" designation="EVENT" initialAlarmState="UNACK_SILENT">Endpoint {name} enabled</eventConfig>
<eventConfig eventType="System.RemoveNotInService" severity="3" designation="EVENT" initialAlarmState="UNACK_SILENT">Returned point to service: {point}</eventConfig>
<eventConfig eventType="System.RemoveOverride" severity="3" designation="EVENT" initialAlarmState="UNACK_SILENT">Removed override on point: {point}</eventConfig>
<eventConfig eventType="System.SetNotInService" severity="3" designation="EVENT" initialAlarmState="UNACK_SILENT">Point removed from service: {point}</eventConfig>
<eventConfig eventType="System.SetOverride" severity="3" designation="EVENT" initialAlarmState="UNACK_SILENT">Point overridden: {point}</eventConfig>
<eventConfig eventType="System.SetpointIssued" severity="3" designation="EVENT" initialAlarmState="UNACK_SILENT">Updated setpoint {command} to {value}</eventConfig>
<eventConfig eventType="System.UserLogin" severity="5" designation="EVENT" initialAlarmState="UNACK_SILENT">User logged in: {user}</eventConfig>
<eventConfig eventType="System.UserLoginFailure" severity="1" designation="ALARM" initialAlarmState="UNACK_SILENT">User login failed {reason}</eventConfig>
</eventConfigs>
</events>To add a configuration entry, add a new eventConfig element like so:
<eventConfig eventType="UserEventType" severity="5" designation="EVENT" initialAlarmState="UNACK_SILENT">User defined event</eventConfig>Then re-import the XML configuration:
ubuntu@ubuntu:~/greenbus-3.0.0$ bin/greenbus event-import mgsite_events/event-config.xml
== Progress:
.
== Finished in 75 ms
ubuntu@ubuntu:~/greenbus-3.0.0$The CLI can be used to confirm the presence of the new event type:
system@127.0.0.1> event-config:list
EventType Dest Sev Audible Resources BuiltIn
-------------------------------------------------------------------------------------------------------------
System.ControlIssued | EVENT | 3 | false | Executed control {command} | true
System.EndpointDisabled | EVENT | 3 | false | Endpoint {name} disabled | true
System.EndpointEnabled | EVENT | 3 | false | Endpoint {name} enabled | true
System.RemoveNotInService | EVENT | 3 | false | Returned point to service: {point} | true
System.RemoveOverride | EVENT | 3 | false | Removed override on point: {point} | true
System.SetNotInService | EVENT | 3 | false | Point removed from service: {point} | true
System.SetOverride | EVENT | 3 | false | Point overridden: {point} | true
System.SetpointIssued | EVENT | 3 | false | Updated setpoint {command} to {value} | true
System.UserLogin | EVENT | 5 | false | User logged in: {user} | true
System.UserLoginFailure | ALARM | 1 | false | User login failed {reason} | true
UserEventType | EVENT | 5 | false | User defined event | false
system@127.0.0.1>Finally, shutdown all the long running processing by calling stop:
ubuntu@ubuntu:~/greenbus-3.0.0$ bin/greenbus simulator stop
Stopping simulator.
Waiting for simulator to stop....
ubuntu@ubuntu:~/greenbus-3.0.0$ bin/greenbus processing stop
Stopping processing.
Waiting for processing to stop....
ubuntu@ubuntu:~/greenbus-3.0.0$ bin/greenbus services stop
Stopping services.
Waiting for services to stop....
ubuntu@ubuntu:~/greenbus-3.0.0$