Connection:fncs msg

Overview
The fncs_msg object is part of the connection module. It allows GridLAB-D models to be run as federates in a FNCS co-simulation. Starting in 4.0 this object is not available in the default 4.0 distribution of GridLAB-D but can be compiled with FNCS from the source code. In 4.1 the fncs_msg object is available by default.

Enabling the fncs_msg object
Prior to the 4.1 release of GridLAB-D the fncs_msg object must be custom compiled from source code by dynamically linking with the FNCS library. FNCS is a third party library that can be downloaded and built from here. Once FNCS and its third party libraries, ZeroMQ and CZMQ, have been built, the following option needs to be added to the configure step for compiling GridLAB-D.

--with-fncs=

Environment Considerations
Prior to the 4.1 release of GridLAB-D the OS environment must be properly set up to run the FNCS library from GridLAB-D if FNCS was installed to a custom location and not the system default. The following environment variables must have the location to the FNCS library and it's third party libraries, ZeroMQ and CZMQ.

Fncs_msg
The fncs_msg object implements the FNCS library such that a single GridLAB-D model acts as a single FNCS federate. There can only be one instance of a fncs_msg object per GridLAB-D model.

Default Fncs_msg
A minimalist fncs_msg could be created with object fncs_msg{ name federate1; option "transport:hostname localhost, port 5570"; configure federate1Configuration.txt; } Which is the same a specifying object fncs_msg{ name federate1; option "transport:hostname localhost, port 5570"; message_type GENERAL; configure federate1Configuration.txt; }

Configuration File Syntax
The configuration file defines the publication and subscription topics as well as the broker location options. The syntax differs based on message_type used.

GENERAL Configuration
the GENERAL messaging structure assumes that each message published and recieved contains a value for a single object's property. So every topic that the FNCS federate publishes or subscribes to corresponds to a specific object's property. The syntax for subscribing to a topic is shown below. subscribe "precommit|presync|sync|postsync|commit:object_name.property_name <- topic"; An example subscription that write the data from a topic to the cooling_setpoint of a house would look like subscribe "precommit:house1.cooling_setpoint <- federate2/house_cooling_setpoint"; The syntax for publishing to a topic is shown below. publish "precommit|presync|sync|postsync|commit:object_name.property_name -> topic"; Below is an example for publishing a house object's indoor air temperature to a specific subtopic publish "commit:house1.air_temperature -> house1_indoor_air_temperature"; Remember that the actual topic that gets published is prepended with the fncs_msg objects name. so If the name of the fncs_msg object is federate1 then the topic that house1's indoor air temperature its published on is federate1/house1_indoor_air_temperature. The precommit|presync|sync|postsync|commit choice determines when GridLAB-D will publish or update the properties during each exec cycle. If you are not sure where in the exec cycle to publish or update a property then, in general, precommit is best for subscriptions and commit is best for publications. a tolerance can be specified for which a property is published. an example is shown below publish "commit:house1.air_temperature -> house1_indoor_air_temperature; 5"; Now the GridLAB-D federate will only publish house1's air_temperature property only if the property has changed by 5 degrees. Please Note!!!: Object names cannot contain "<", ">", or "-" as the line parser will fail to parse the publish ad subscribe lines correctly if they do contain them.

JSON Configuration
the JSON messaging structure was designed specifically for the GridAPPS-D Platform. It hardcodes the FNCS federate to publish all variables listed in configuration file on one topic in a json structured string and to subscribe to specific topic. It also hard codes the fncs_msg object to always request 1 second time steps. The hardcoded publication topic is /fncs_output and the hardcoded subscription topic is /fncs_input. The configuration file is expected to be a json formated file with the following schema {     "globals" : [, ...], : [, ...],     ... } The example shown below shows how to publish the simulation global clock, the tap positions on a regulator and a house's air temperature. {     "globals" : ["clock"], "regulator12" : ["tap_A", "tap_B", "tap_C"], "house23" : ["air_temperature"], }