search

SignalK / specification

Signal K is a JSON-based format for storing and sharing marine data from different sources (e.g. nmea 0183, 2000, seatalk, etc)
Other
91 stars 69 forks source link

Proposal for "Circuits" object for switchable electrical objects #187

Open faceless2 opened 8 years ago

faceless2 commented 8 years ago

This issue is intended as a starting point for discussion on how to represent electrical items other than batteries.

My mental division is batteries, and everything else. The reason for this is that batteries are always there and store charge, so we need to know things like capacity. Everything else is both switchable and transient: if it's not a battery it cannot store charge, so we're only interested in how much it's putting into or taking out of a battery. There are enough similarites between a load (eg cabin light) and a charging source (eg PV panel) that they can be lumped together; some, e.g. an outboard motor with alternator, can function as both a load and charger.

My label for things that aren't batteries is "circuits" and here's a sample model, by no means a concrete proposal but it does express a few ideas I've had. It's derived from a slightly simpler model I've been using which has evolved over time, so I know it works, although I only have DC and one system voltage. At this point I can't see any reason why this couldn't apply equally to AC, particularly if we have a "supply" object or something like it as described below.

"electrical": {
    "circuit": {
        "Tricolour": {
           "type": "switch",
            "id": 20
            "group": "Lighting",
            "current": -1.2,
            "maxcurrent": -1.8,
            "mincurrent": 0,
            "tripcurrent": 2.5,
            "tripdelay": 0.0025,
            "state": "on",
            "transitions": ["off,"alt"],
            "url": "/action/circuit/{id}/{state}",
            "location": "Switchboard A, top left".
            "supply": "HouseBattery"
            "timestamp": "2015-01-01 00:00:00"
        },
        "Outboard": {
           "type": "switch",
            "id": 21
            "group": "Other",
            "current": 4,
            "maxcurrent": 4.2,
            "mincurrent": -75,
            "location": "Hanging off the back of the boat"
            "supply": "EngineBattery"
            "timestamp": "2015-01-01 00:00:00"
        }, ...
    }
}

type A constant. For now I am defining one value, "switch", but others could be possible (eg "dimmer"). Including this here allows for this structure to be expanded later if needed. For brevity a value of "switch" could be an implied default?

id A unique numeric id to reference the device. The name, which I have as the key for the entry in the map, is also unique. I expect both will be useful, the name is required for any UI and a numeric ID is more useful for URLs constructed to reference this device. Opinions on exactly how these are to be stored in the datastructure are most welcome.

group A useful way to visually lump together circuits in a UI - for instance we've all got several lighting circuits. Someone above mentioned hierarchy for circuits, I'm not against it but if you think about a typical hardwired switchboard there's typically no concept of hierarchy. At best you'll get a rectangle about a group of switches called "lighting" or "ac" or whatever. I have 18 circuits and I've found this to be adequate visually in the UI with that number. It obviously won't scale to hundreds, the question is will it need to.

current, maxcurrent, mincurrent, tripcurrent With any circuit you're interested in load to/from the battery, and that means amps. I have a very vague collection of chatting about this with @timmathews many months ago and discussing whether it was Watts or Amps. I'd strongly suggest Amps, because:

Positive values are charging the battery and negative are discharging. Trip current is always an absolute value: a fuse is there to protect the wire, and the wire doesn't care about current direction. (Note I have used "trip" rather than "fuse" as with resettable circuit breakers, it's normally referred to as a trip current.)

I would strongly suggest that exactly how to define each current is left out of the specification as implementation dependent. For example, "max" and "min" current are peak loads, so it's fair to measure them as a point sample. But the current right now (can I say current current?) is better represented as a running average: if I have an LED cabin light at 50% brightness I am probably PWMing the lights, and the instantaneous current at any point is going to be very misleading. Some sort of averaging is appropriate, and this should be left to the device reporting it. The same applies to "trip" current - some devices (see below) allow the trip delay to be configured, others might have more complex algorithms. It's very device-dependent, and we should not hamper implementers by over-specifying these fields. If necessary we should say that the current values are "the best estimate of the current used by the device".

In the example above, the "Tricolour" circuit is a load - it has a negative current, and is switchable. The "Outboard" is both a load and a source - the example above is intended to show the outboard has drawn 75A while being started, but is now charging the "EngineBattery" with 4 amps from its alteranator. It's not switchable and not fused.

I'd also suggest that "maxcurrent" and "mincurrent" are optional and default to zero, so save us needlessly specifying one of these for items that are always loads or supplies.

tripdelay is in seconds. I was initially unconvinced about the value of this field, but some devices (eg http://www.carlingtech.com/sites/default/files/documents/Octoplex_rev6_op.pdf) allow this to be set. Others do not, so this should always be optional.

state The state of a switchable circuit is more than "on" or "off". My Tricolour can be reversed to show an all-round white for anchoring, and any electronically controllable valve would have "opening" and "closing" as valid states alongside "open" and "closed". A computer might have "shutting down" before it moves to "off". So I'd suggest leaving this fairly open for a UI - perhaps define a few known states such as "off", "on" and "tripped", and leave everything else visually as a variation of "on".

transitions What really matters to the UI are state transitions that can be actioned by the user - if my switch is "tripped" I can transition to "off" to reset it. If it's "off" I can normally only transition to "on", but my tricolour can transition to "on" or "alternate". That's the idea of this field. While it's possible to imagine many states for a circuit, it's difficult to imagine more than two possible transitions that could be actioned by the user at any point in time (this applies for a type of "switch", of course. Other methods of transition are possible for devices like dimmers).

url Once you have state and a list of valid transition states, all you need on top is a URL to call with the new state to allow a UI to represent a switch and allow the user to turn that switch on and off. (Note: Where and how to store this in the datamodel is open for debate - for a start, the URL template will likely be the same for all switches, so why store it here?)

location is to define the location of the physical switch this circuit represents. I'm not sure how to do this other than a text field, or it's usefulness, but it was raised as an issue, and metadata never hurts.

supply is to reference this circuit back to the battery (or other power store, e.g. inverter) that it is connected to. While "source" would be the obvious name for this, that term is used elsewhere in SignalK with a different meaning so trying to find an appropriate other term would be a good idea. The intention is this would be a reference to a unique ID of an item elsewhere in the SIgnalK electrical hierarchy.

(Originally posted to slack, reformulated as an issue and modified slightly to reflect some of the comments)

faceless2 commented 8 years ago

183

faceless2 commented 8 years ago

I should amend the above: the specific exception to things that "put charge in and out of batteries" are inverters, which act as a current source (for AC) and a current sink (for DC). Not sure how to model these, they are a bit of an exception.

sumps commented 8 years ago

@faceless2 this was a really good issue and I am just sorry that it came at a time when we were all focused on getting V1 of Signal K released. On reading @mark-tilden reference to your issue, it reminded me how good your post had been and I am sorry that no one commented to this effect at the time.

I would like to support getting this issue on to the V1.1 wish list as it would be a great application for showcasing Signal K control, rather than just listening as we do at the moment.

faceless2 commented 8 years ago

Cheers Paul. I didn't follow it up either as I have been too busy trying to actually finish my boat (finally launching this week after three years building). I hope to return to signalk in a few weeks to pick up with my agitating where I left off!

Would also love to hear how this ties in with @kees setup, as I know he also has computer controllable circuits. No doubt others have fashioned their own setups too. The wider base of installed systems we can build this aspect of the specification from, the better.

keesverruijt commented 8 years ago

Would also love to hear how this ties in with @kees https://github.com/kees setup, as I know he also has computer controllable circuits. No doubt others have fashioned their own setups too. The wider base of installed systems we can build this aspect of the specification from, the better.

In lurking mode for the last few weeks, but yes I’ll chip in. My computer controllable circuits are driven by a small WAGO PLC running Linux, and my own C program that uses JSON to report on status and REST to change the status. Now where did I hear that before :-)

thomasonw commented 8 years ago

facelsess2: Hello. Noted this open issue and idea. I think you are correct, adding an object to address switches is appropriate. I am wondering if perhaps it could be generalized a bit. With the concept of 'buses' being a way to ID linkage of different devices, could we use your proposed 'Circuits' (or another name..) as a way to handle not only switches, but also fuses/circuit breakers - things that provide connection / disconnection between two buses.

Do wonder though if this needs to be in the v1 release - or post release addition.