So in my endeavours to bring Node-RED to the masses, I have written a short piece on the terminology of Node-RED. The intention is to reuse this text in other articles, so I've tried to keep in encapsulated.
I would love to get feedback on whether there is anything completely way-off from the language used within the community, e.g., is it links, wires or connections? Wires seems to be the term to be using.
Anyway I hope its worth reading, it has an epic ending!
Great article would scan it again in an instance -- ChatGPT.
Nothing in this piece is really wrong, but some things are off by just enough that I would hesitate to recommend it to a newcomer to Node-RED. The Node-RED Concepts section of the documentation covers much of the same ground without any of the minor issues I find in your piece. Some examples:
Wires, definitely (see the documentation). "Links" should be reserved for the link nodes. When "connections" are made by the network nodes (http, mqtt, tcp, etc.), they may be temporary.
Flows are visual code, programs that describe the modification of data
This is correct in the context of flow-based programming, but unfortunately in Node-RED the term "flow" has become overloaded in ways that can cause confusion. The relevant part of the Concepts documentation is the developers' best effort to deal with this.
Node-REDs convention is that the data object passed into a node is called msg .
This is a bit muddled. From the documentation,
Messages are what pass between the nodes in a flow. They are plain JavaScript objects that can have any set of properties. They are often referred to as msg within the editor.
By convention, they have a payload property containing the most useful information.
You don't actually mention "messages" until almost the end of the piece, but the term should be used throughout.
Other thoughts: you should at least mention context variables and the distinction between the editor and the runtime. I think your efforts to promote the use and understanding of Node-RED are very valuable, and I hope you take these comments as a constructive effort to improve your document.
[EDIT]
Connectors are the small squares attached to the nodes.
These are "ports" not "connectors," and they are circles in the standard version of the editor.
Cheers for the feedback, much appreciated I will definitely include your feedback in my revisions of the article.
Hm, that makes it difficult to exactly explain what a collection of nodes + wires actually represent. For me node + wires = flows ==> code ==> programs that do stuff. What is the term to be used instead of flow? Even the homepage uses flow in this sense:
It provides a browser-based editor that makes it easy to wire together flows using the wide range of nodes[...]
The term "flow" is definitely not easy to nail down.
It simplifies the explanation, I will definitely do that. You also correctly point out my inconsistence with the term "message" - I will fix that too.
Squares or circles? They look like squares to me! At least on the nodes, on the link nodes they are circles but squares on the opposite side of the link. Now I'm confused!
That's from v3.0.2 - for me: a circle, a rectangle (hm, square in this case), a square and the beginnings of a line, for Node-RED a link input port, a node, an output port and the beginnings of a wire. The port does seem like a square to me - the output port!
I'd rather do that in other articles, I think I will keep this article more focused on the concepts before getting into the technical workings of Node-RED. Also this is intended to be a text snippet that I can use in other articles.
To a certain extent, what the article shows is my own confusion and thereby mirroring the potential confusion of others. Once my confusions are gone, I can't write about them, so best to write now!
What I also wish to say is that to an extent it doesn't matter what one calls the "rectangles" and "lines" as long as one has understood the basic concepts of flow programming, one can use but perhaps not 100% understand Node-RED.
The reason why I refer to rectangles and lines is because that is what many people see initially. I see Node-RED as something that non-programmers can use to create programs. So the common language IMHO, the overlap between programmers and non-programmers in this case, becomes shapes. Hence the low-level beginnings of the article.
I'm sure my article would pass the Turing test, but would it pass the Grandmother test? (i.e. does grandmother understand how to use Node-RED?) - The Grandmother test is what I'm aiming at.
Thank you for providing such detailed feedback Responding to your comments has given me a better focus for what I want to achieve with the article and clarified my thoughts
@drmibell based on your feedback, I've come with a completely different article
I've changed the terminology but also the point of the article: instead I promote the use of a visual programming paradigm instead of trying to introduce the Node-RED terminology. From there I can go to what I actually want to write about: refactoring in a visual programming environment and some best practices using Node-RED.
I proposed in the past (but got a pushback from dev team as such change would be too pervasive & impactful) to clear the confusion around the overloaded term "Flow".
In an ideal world, the terminology would differentiate between:
The whole "Workbook" (the full set of editor tabs, configured in a flows file instance)
A "Tab" (within the workbook)
A set of connected nodes (within or across tabs). Could be called "flow", "map", "blueprint" etc.
A sequence of messages, initiated/injected through a set of connected nodes ("run", "stream", "injection", "msg sequence" etc.)
Again, maybe too late to change now, but would have resolved some ambiguity.
I was just thinking of Jupyter, they use "notebook": perhaps Node-RED could use "Flowbook". Then the extension could become .jfb (theirs is .ipynb from ipython + notebook)
"run" is also good - a "flow run" for an execution of a flow?
But definitely agree with your suggestions, sound sensible to me.
My 2 cents on terminology...
For me, the most confusing is "flow".
It can be either a tab (so "sets of connected nodes") or one set of connected nodes.
Calling two different things with the same word is quite confusing.
Especially when the flow context for variables means in fact the tab context
And, from I can tell, there is no "set of connected nodes" variable which has made my life difficult in a few cases.
Visual programming is a paradigm shift away from editor-based programming to a visually interactive context. With this shift comes new challenges and new approaches to programming.
This makes me feel like the sort of fossil that belongs in a museum. I learned to describe algorithms with flowcharts before I ever wrote a line of code. The goal of automatic translation or compilation of diagrams into executable code has been a theme of computer science for decades and has helped
motivate development of important programming languages and markup languages. I guess Node-RED deserves credit for reminding us of that "ancient history."
UML, the good old days! But they never managed to have diagram and code in sync, i.e. change diagram --> code changes and/or code changes --> diagram changes. It was always model the diagrams, generate code one time, change code, update diagrams by hand ....
The holy grail of UML, SysMLv2 and BPMN ... and the rest. (Although apparently there have been successful projects in the SysMLv2 world that has managed to keep the two in sync ...)
That's why I find Node-RED so inspiring since it combines the two and keeps them in sync and that in the browser! Pity that Node-RED hasn't yet found wider adaption into areas that aren't IoT...
Btw I can top that: I wrote code, then drew UML diagrams, then went back to coding and now I'm drawing again ... hm ... history, rinse, repeat.
Yes, that's a hot mess. Is the diagram the design or the documentation? If the programmers can force changes in the diagram, then where is the architecture, and who is responsible for it? I may actually have been lucky to work in organizations that were too rigid and bureaucratic to allow anything like that.
NodeRED tends to refer to this as "Low-Code/No-Code", but that isn't true. There's very little one can achieve without resorting to JavaScript. Very little indeed.
I used NR as an add-on to Home Assistant, but as HA has grown to include if-then-else and support for PyScript, I find that I no longer need NR. Most automations are easier to do in HA as-is, until someone comes up with a true "No-Code" version of NR.
No-Code certainly not, low-code very much so - IMHO.
I initially thought that too but then began using the in-house nodes such as switch, change, template, and so on to reduce the usage of the function node. What really helped was learning JSONata which can do most of what I ended up doing in the function node.
For example this change node + jsonata does the same as this function node. As in this example, I still find myself using the function node where a change node would also be usable - that's refactoring that I need to do.
Of course I always have something that isn't covered by a node and so I end up using a function node but that code is to the point, i.e. there is no converting between formats, there is no http requests to get the data, there is no boilerplate code. The function code tends to be very explicit functionality that is required at a specific point in the flow.
It is unfair to say you can do "little" "without resorting to JavaScript" then big up HA which makes you use an own if-then-else logic + pyscript. PS there are good reasons to learn JS over pyscript - example
There is far more you can do in node-red without ever writing JS. You can chose to do JS if you are comfortable with it - ask @cymplecy - he uses NR extensively and pretty much refuses to touch JS.
that's node-red - it's because your in the NR editor and it does not wish that you leave.
How many grains of sand make a hill? Start with a single grain and then add grains individually, each time ask yourself is that a hill.
Where does "low code" begin? Where does "no code" end? What do I know and why would I want to argue against your opinion that not using the function node is not low code - which, btw, I didn't say. What I was pointing out was that using the in-house nodes makes less usage of function nodes and less function nodes is less code (by definition since you're not using msg.ZZZ = YYY all the time).
Either way, typing a telephone number into a phone is coding: how else would the machine know whom to call? If I use an address book is that then low-code or no-code?
Hint: everyone has their own definition for low-code and no-code (since it comes down to experience), to claim tool X is low-code while tool Y is no-code is a bunch of marketing.
onpaletteadd: () => {
var nodeId = window.location.hash.match(/\/n\/([^\/]{16})(\/edit)?/);
// RED.nodes is not initialised at this point, so there is no way to
// check whether the nodeId really does exist, so we assume that nodeId
// will be eventually addded to a workspace.
if ( nodeId ) {
var hndlr = (node) => {
if ( node.id == nodeId[1] ) {
setTimeout( function() {
var nde = RED.nodes.node(nodeId[1]);
RED.workspaces.show(nde.z,false,false,true);
if ( nodeId[2] == "/edit" ) {
RED.editor.edit(nde);
}
RED.view.reveal(nodeId[1],true);
}, 1012);
RED.events.off("nodes:add", hndlr);
}
};
RED.events.on("nodes:add", hndlr);
}
// Highlight an entire path.
var pathIds = window.location.hash.match(/\/p\/((.{16},?)+)/);
if ( pathIds ) {
var nodeIds = [];
pathIds[1].split(",").forEach( function(ndeId) {
if ( ndeId.trim() != "" ) { nodeIds.push( ndeId.trim() ) }
});
var hndlr = (stst) => {
if ( stst.state == "start" ) {
setTimeout( () => {
RED.workspaces.show(RED.nodes.node(nodeIds[0]).z,false,false,true);
RED.view.selectNodes({ selected: nodeIds });
}, 321);
RED.events.off("runtime-state", hndlr);
}
};
RED.events.on("runtime-state", hndlr);
}
},
This simulates the deep linking functionality that is coming in 3.1.x for NR 3.0.x. Clarification: highlighting a node via a url, not deep linking associated with the link nodes.
I assumed that I manipulate the window.location value and push something on the stack but that's not the case. So not really sure what is going on. I definitely don't wish to break the back button and thanks for pointing it out ... fixing is now the problem.
EDIT: It does seem to be a Node-RED issue but only on Firefox, e.g., link to node tab will change the location twice:
Opera will combine these two and the back button isn't affected. Firefox with have two locations in the history that point to the first flow tab and the intended flow tab.
I will definitely include your feedback in my revisions of the article.
Even the 
