Package: btnexus-node-python
Blackout Nexus Node for PythonAuthorAdrian LubitzAuthorMarc FiedlerEmaildev@blackout.aiRequired Instance versions>= 3.0Runs onPython 2.7+ or Python 3.6+StateStablePrerequisitesPython installed (either 2.7+ or Python 3.6+)Owner of a btNexus instance or a btNexus accountInstall btnexus-node-pythonpip install btnexus-node-pythonIf you need to install a specific version usepip install btnexus-node-python==[VERSION]API DocumentationYou find an API Documentation ourGitHub PageIntroductionThenexusby Blackout Technologies is a platform to create Digital Assistants and to connect them via the internet to multiple platforms. Those platforms can be websites, apps or even robots. Thenexusconsists of two major parts, first being thebtNexusand second the nexusUi. ThebtNexusis the network that connects the A.I. with the nexusUi and the chosen interfaces. The nexusUi is the user interface, that allows the user to create their own A.I.-based Digital Assistant. Those Digital Assistants can be anything, support chatbots or even robot personalities.Every user has one or multiple nexusUi instances or short nexus instances, which means, it's their workspace. One nexusUi / nexus instance can host multiple personalities.Every part of thebtNexusis a Node. These Nodes can react on messages and send messages through thebtNexus. To understand how Nodes work the following key concepts need to be clear.NodesNodes are essentially little programs. It is not important in which language these programs are implemented.
More important is that they shareMessagesbetween them in certainGroupsandTopics.
So every node has its very unique purpose. It reacts onMessageswith aCallbackwhich is subscribed to aGroupand aTopicand also sendsMessagesto the same and/or otherGroupandTopicto inform otherNodes, what is happening.MessagesMessagesare the media of communication betweenNodes.
AMessagecontains a name for aCallbackand the corresponding parameters.
AMessageis send on a specificGroupandTopic, so onlyCallbacksthat subscribed to thisGroupandTopicwill react.CallbacksCallbacksare functions which serves as the reaction to aMessageon a specificTopicin a specificGroup.
EveryCallbackreturns aMessageto thebtNexuswith the name of the originCallback+_response. So aNodecan also subscribe to the response of theMessagesend out.Topics & GroupsTopicsandGroupshelp to organizeMessages. ACallbackcan only be mapped to oneGroupandTopic.Example NodesFollowing you will see an example of a Node which sends out the current minute
and second every five seconds."""Example for a Node that sends out messages"""# System importsfromthreadingimportThreadimportdatetimeimporttimeimportos# 3rd party importsfrombtNodeimportNode# local importsclassSendingNode(Node):"""This Node shows how to implement an active Node which sends different Messages"""defonConnected(self):"""This will be executed after a the Node is succesfully connected to the btNexusHere you need to subscribe and set everything else up.:returns: None"""self.shouldRun=Trueself.subscribe(group="exampleGroup",topic="example",callback=self.fuseTime_response)# Here we subscribe to the response of messages we send out to fuseTimeself.thread=Thread(target=self.mainLoop)self.thread.start()# You want to leave this method so better start everything which is actively doing something in a thread.deffuseTime_response(self,orignCall,originParams,returnValue):"""Reacting to the fused Time with a print in a specific shape.responseCallbacks always have the following parameters.:param orignCall: The name of the orignCall:type orignCall: String:param originParams: The parameters given to the orignCall:type originParams: List or keywordDict:param returnValue: The returned Value from the orignCall:type returnValue: any:returns: None"""print("[{}]:{}".format(self.__class__.__name__,returnValue))defmainLoop(self):"""Sending currenct minute and second to the ListeningNode on the printMsg and fuse callback.:returns: Never"""#Make sure the thread terminates, when reconnecting#otherwise onConnected will spawn another#and you will end up with n threads, where n is the number of connectswhile(self.shouldRun):now=datetime.datetime.now()self.publish(group="exampleGroup",topic="example",funcName="printTime",params=[now.minute,now.second])self.publish(group="exampleGroup",topic="example",funcName="fuseTime",params={"min":now.minute,"sec":now.second})time.sleep(5)defcleanUp(self):"""Make sure the thread terminates, when reconnectingotherwise onConnected will spawn anotherand you will end up with n threads, where n is the number of connects"""super(SendingNode,self).cleanUp()self.shouldRun=Falsetry:self.thread.join()exceptAttributeError:pass# This only happens if onConnected was never called before - Node was never connected correctly and therefore closes the connection and calls the cleanUpif(__name__=="__main__"):#Here you initialize your Node and run it.sendingNode=SendingNode()# CONNECT_HASH needs to be in .btnexusrc or environment variable CONNECT_HASHsendingNode.connect()# This call is blockingThe ListeningNode and all further examples can be seen in the examples folder.Implement your own NodeFirst you need know the purpose of your Node.
Nodes should be small and serve only one purpose.
To implement your own Node you need to inherit from the Node class,
implement your callbacks and if you are actively doing something implement your
Threads, that for example read in sensor data. See the examples to get started ;)
Keep in mind, that you need to set theCONNECT_HASHin your.btnexusrcor the environment variableCONNECT_HASH. If you are using Anaconda you can integrate those into your virtual environment(https://conda.io/docs/user-guide/tasks/manage-environments.html#saving-environment-variables).ChangelogSince Version 4 the protocol was changed to completely usesocketIO- Therefore it only works withDynamic Davinci(Instance Version 2.2)Since Version 5, Nodes and all inheriting classes (Hooks, Integrations) use aCONNECT_HASHwhich can be obtained from the Instance and should be given in the file.btnexusrcor the environment variableCONNECT_HASH(The latter overwrites the first). Additionally apackage.jsonfile is needed. It should be minimal the following:{"name":"test","title":"Test","description":"This is just a test","type":"integration","keywords":["test","testing"],"version":"0.2.3","nexusVersion":"2.2","license":"See attached LICENSE file","author":{"name":"Adrian Lubitz","url":"https://blackout.ai/","email":"al@blackout.ai"}}Since Version 6 all Nodes are able to connect to 3.0 Instances