diff --git a/assets/index.json b/assets/index.json index 13a7a8b..b15c678 100644 --- a/assets/index.json +++ b/assets/index.json @@ -1 +1 @@ -[{"relativeUrl":"/what-is-msb","url":"http://127.0.0.1:4000/what-is-msb","title":"What is microServicebus.com?","content":"Ultimately, microServiceBus.com is designed fill the gap between the out-of-the box device management provided by vendors such as Microsoft, Amazon and IBM, and what is required by the enterprise. It aims to address common challenges in the industry of IoT, such as planning for change, steep learning curves and provisioning of new devices. microServiceBus.com is a platform based on agents, also known as Nodes, running on gateways and controlled from a portal known as microServiceBus.com. microServiceBus.com and all related products and services are owned by AXIANS IoT Operation and is part of VINCI-Energies On-boarding new devices is difficult at scale. Gateways need to automatically be assigned a cloud identity, receive keys and certificates. -All in a highly secure manner.\nmicroServiceBus.com provide a scalable, cross cloud vendor solution based either on integration with SIM card management tools like Cisco Jasper or MAC address white-listing. For more information: No part of any system will stand the test of time. Software is constantly updated to align with security threats or new required features.\nUpdates and patching are easily handled through microServiceBus.com by either replacing entire firmware or individual services. Updates can be done manually or scheduled through tasks. This can be done for single devices or groups of devices.\nEasy deployments to IoT devices facilitates Agile development! For more information: Source code and services are not only deployed to devices, but need to be audited and versioned to ensure the end-to-end business process.\nWith complete insight and traceability, code can be fully managed and versioned within the microServiceBus.com portal. However, we also integrate with Git repositories such as GitHub and Azure DevOps. For more information: Identifying and resolving problems can be a difficult mission in any system, but spread over many thousands of remotely located units brings it to a whole other level!\nmicroServiceBus.com provides great insight to what is and has happened on the device. Through it’s tracking capabilities, developers and operation staff can gain understanding of what is happening, and even remotely debugging the code, and instantly deploy fixes. For more information: microServiceBus.com extends to a complete Application Lifecycle Management system through its integration with 3rd party vendors, and continues to expand through its extensive API.\nAs of today, microServiceBus.com integrate with ServiceNow for Issue, problem- and release management, allowing customers to align their existing service desk and Nightly Operation Center (NOC). Integration with Cisco Jasper makes way for a compete SIM card management, along with GitHub, Azure DevOps, Active Directory and more. For more information:"},{"relativeUrl":"/installing-microservicebus-node","url":"http://127.0.0.1:4000/installing-microservicebus-node","title":"Installing microServiceBus-node","content":"microServiceBus-node is the agent that needs to run on your device, and requires node.js and npm to be install prior to installing the agent. Node.js® is a platform built on Chrome’s JavaScript runtime for easily building fast, scalable network applications. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient, perfect for data-intensive real-time applications that run across distributed devices. Node.js provides lost of useful scenarios outside the scope of microSeviceBus.com® and as such it can be used together with other applications and solutions deployed on Node.js. Along with Node.js comes npm, which is a package manager for Node.js along with other things. After installing Node.js, you can use npm to install the microServiceBus.node package, and from there, you’re pretty much set to get started. To complete this process, just follow these three steps: To install Node.js go to https://nodejs.org/download/ and download the installation media for your platform. Make sure you install the npm package manager as well. Download the latest stable version and install the msi using the default settings. This will install both Node.js and npm. Be aware that if you want to run microServiceBus-node as a daemon you need to install the agent as root! If you are on a Ubuntu or Debian operating system you simply open a terminal and use the following command: \nsudo apt-get update \nsudo apt-get install nodejs While there, continue to install npm using the following command: To make npm work on a Raspberry Pi you might need to set the registry to HTTP using this following command: For a fully manageable Raspberry Pi, consider using the Raspberry Pi Yocto Image for more info: Installing node on raspberryPi Open a terminal or command window and create a directory of your choice. Then type the following: This command creates and installs the package in a folder called node_modules. Browse to the node_modules/microservicebus-node folder. \nBefore you start your node, you need a temporary verification code which you can generate from the Node page. With the microServiceBus-node installed we need create the node in the microServiceBus.com portal. There are a number of ways to create and automatically provision nodes. For now, we’ll keep it simple and use the Nodes page. Navigate to the Nodes page and create a node using the CREATE NEW NODE button on the top. Give the node a name and description and hit CREATE. Back at the the Nodes, your new Node should be visible in the list. With the microServiceBus-node package installed and the Node created in the portal, it’s time to start the node. The first time you start the node, it has no knowledge of what organization it belongs to nor does it have any access keys to authenticate to microServiceBus.com or you IoT hub for that matter. There are many ways you can pre-configure the node before it’s started, but again we’ll keep it simple. On the Nodes page in the portal, click the GENERATE button. Copy the generated verification code and go back to your terminal or console. The verification code is unique and valid for 30 min, and can be used to configure a node.\nIn your terminal/console, type the following: This should start the Node, which should begin by downloading microServiceBus-core, which together with microServiceBus-node make up the agent that we generally refer to as “The Node”. The installation should complete after a couple of minutes, after which it will authenticate it self using the temporary verification token you generated before. In the final step before completion, the Node will install the necessary packages for communication with your IoT hub, after which you should see you *Node online in the portal. If you want to stop the Node, simply hit CTRL+C/CMD+C in the terminal/console. To start it up again, simply type: Step 1: Create A Unit File Open a sample unit file using the command as shown below: Step 2: Add in the following text : Step 3: Set permissions\nThe permission on the unit file needs to be set to 644 : Step 4: Configure systemd\nNow the unit file has been defined we can tell systemd to start it during the boot sequence:"},{"relativeUrl":"/running-microservicebus-node-on-a-yocto-image","url":"http://127.0.0.1:4000/running-microservicebus-node-on-a-yocto-image","title":"Running microServiceBus-node on a yocto image","content":"Yocto is an huge topic and to get you started we are going to setup an Raspberry Pi to run an custom pre built Yocto image. The pre built image contains 4 partitions with some key parts that enables microServiceBus.com to do remote firmware updates. If you have previous experiences with Yocto and only looking to include the microServiceBus agent to your build have a look at meta-microservicebus-node The boot partition contains the bootloader, in this case U-Boot. The bootloader is first to run after power up. U-Boot is responsible to load the Linux kernel into memory and decide if RootFS 1 or 2 should be mounted by the kernel. In the rootfs partitions all Linux user space software is installed. There is two rootfs partitions to be able to update and swap firmware, only one is active at a time. The software most interesting for us is microServiceBus-node and RAUC. microServiceBus-node is responsible for installing and updateing microServiceBus-core. microServiceBus-core will check for new firmware, if newer firmware exists microServiceBus-core will download firmware and then call RAUC to install and swap rootfs next boot. Data partition is used to store data that will be persistent between firmware updates. microServiceBus-node runs by “msb” user whose home directory is located under /data/home/msb. The microServiceBus agent stores scripts and data under the home directory by default. The Yocto Project is an open source collaboration project that helps developers create custom Linux-based systems regardless of the hardware architecture. Yocto build system runs on Linux but this tutorial will use pre build files and is targeted Windows as an host system. In this tutorial we will use target to reference the Raspberry Pi and host to reference the PC used to write the SD-card. Tip! For more info regarding Yocto please visit Yocto project This image use RAUC software to apply firmware updates. microServiceBus-node will download new firmware from mSB.com and call RAUC install over d-bus to trigger the update.\nRAUC use X.509 cryptography to sign the update bundles, in this tutorial the example bundles is signed using an demo key. Tip! For more info regarding RAUC please visit RAUC To follow along this tutorial you need some hardware. Here is some software that is good to download/install before moving on The Raspberry Pi setup use SSH-keys for authorization when connection with SSH from host. If you already have an public and private key pair you can skip this section. To create an SSH-key pair follow the steps below. Tip! If you have problem you can follow this guide This will erase all content on the SD-Card, backup any data before continuing! To add your public SSH-key to the Raspberry Pi image you need to create an authorized_keys file. An init script will copy your key to the active rootfs on boot, you can use an USB flash drive or place the file on the boot partition on the SD-card. Your file should look something like below: If you use cable to connect to LAN you can skip this section.\nAs the Raspberry Pi is intended to run headless(no display) and be able to swap rootfs without losing your WiFi settings an configuration file can be copied to the boot partition. An init script will copy your configuration file to the active rootfs on boot, you can use an USB flash drive or place the file on the boot partition on the SD-card. WPA-Supplicant is used to setup WiFi on the Raspberry Pi. WPA-Supplicant template for WPA and WPA2: Tip! For more info regarding WPA-Supplicant conf you can read here To start microServicebus-node on the Raspberry Pi an service file is used to auto start it and restart it in case of failure. There is an default service file on the SD-image already but you can add an custom service file to the boot partition to set different configurations for microServiceBus. We are going to use this to set sign in name and verification code. The default service file use white list and MAC address for sign in. An init script will copy your service file to the active rootfs on boot, you can use an USB flash drive or place the file on the boot partition on the SD-card. microServiceBus-node service template: At this stage you hopefully have an working SD-Card to use in your Raspberry Pi. If you like to see the boot process connect an HDMI display to your Raspberry Pi and an keyboard to be able to interact. But if all off the above configuration is correct your Raspberry Pi node should come online in mSB.com if it have internet access. An SSH-server is running on the Raspberry Pi by default and allow connections using SSH-key authentication. If your configuration above is correct the generated public SSH-key have been added to ~/.ssh/authorized_keys and will grant you access. If the address is empty the node may have been assigned an IP late or after fully booted, press enter to reprint the prompt. Default there is no root password, thus login local with keyboard is not possible. You need to authenticate with SSH-Key. Enter the Raspberry Pi address Now we have to select our private SSH-key, in the tree to the left open Connection->SSH->Auth, then browse your private key. Note, this password will not be permanent when you do firmware update later. Tip! If you have problem this guide may help When using Yocto and RAUC microServiceBus enable the possibility to do remote firmware updates. In this setup we will only update the rootfs but RAUC have the possibility to update kernel, data partitions or even the bootloader it the target hardware have support for it. Follow the steps bellow to upload and apply an new firmware to your target. In rootfs0 you should see “state”: “inactive” and in rootfs1 “state”: “booted, this indicates that your node now have booted to your new firmware on rootfs1 Back to home page: Home"},{"relativeUrl":"/common-commands","url":"http://127.0.0.1:4000/common-commands","title":"Common Linux termnal commands","content":"grep and awk sample vi or vim is a commonly used file editor, which can be complex to use, but here are a few commands to get you started. less is a great tool for analyzing log files. systemd is a software suite that provides an array of system components for Linux operating systems, such as daemons (services). systemctl is the tool you use to interact with systemd journalctl is also part of the systemd suite and helps you view logfile in real-time. journalctl -u [service] -n [number of previous lines] -f . E.g."},{"relativeUrl":"/get-insight-using-tracking","url":"http://127.0.0.1:4000/get-insight-using-tracking","title":"Get insight using tracking","content":"Though the Console can give you valuable understanding of the execution of your Services, it might not provide insight into your overall processes and messages. -This is where Tracking comes to the rescue. When enabling Tracking for a Node, the message along with its context for every executed Service will be transmitted to the Tracking database of microServiceBus.com. The data will be automatically deleted after 30 days, but is the single exception to storing content- (payload) and context data (meta data) in microServiceBus.com. Apart from this exception, sensor and meter data sent to the IoT Hub never passes microServiceBus.com. That being said, it’s a valuable tool when identifying and resolving issues. By default, Tracking is disabled, and you should always remember to disable it when your are done as Tracking will add extensively to your data usage. To enable the Tracking, navigate to the Nodes page, and simply toggle the Tracking button of the Node you’d like to work with. Navigate to the Management page using the menu, click the Tracking tab at the top. If your Node has executed any Services since you enabled Tracking you should see a list of events: Each line represents one execution of your Flow. Select one of the instances by clicking the View Details button. This takes you to a new window, showing a snapshot of the state after each Service executed. The first tab shows you where in the flow the snapshot was captured. The other tabs reveal any errors, what the payload (content) looks like but also variables and metadata (context)."},{"relativeUrl":"/using-the-console","url":"http://127.0.0.1:4000/using-the-console","title":"Using the Console","content":"microServiceBus.com comes with a Console feature which provides similar output as you’d have through a terminal. Enabling Console output is a very powerful and common way to debug your Service and Flow. It will provide you with insight of how your Services behave and any issues you might experience. By default, Console output is disabled, and you should always remember to disable it when your are done as Console output will add extensively to your data usage. To enable the Console output, navigate to the Nodes page, and simply toggle the Console button of the Node you’d like to work with. Without doing anything else, you will only see default output from the Node. To write your output from your Service, leave the Console window open, and open up a new window and navigate to the Service script and open the editor. To write to the Console output, use the Debug function as: Debug statements will work as console.log() and will always be visible in the terminal, however they will only be visible in the Console output if enabled in the portal. Similarly, you can also use the ThrowError function to track errors: Part from sending the exception information to the Console, the ThrowError function also submit tracking information, which can optionally be sent to Issue tracking systems like ServiceNow. The context parameter is optional, and only relevant if it exists such as in the Process function. Use an error number lower than 90000, as error code above are reserved for microServiceBus.com. To view the output, simply navigate to the Console in the portal. Tip: If other developers are using the Console at the same time as you, the output can be exhausting. -Use the filtering option and set it to the name of your Node."},{"relativeUrl":"/integrate-external-ticketing-system","url":"http://127.0.0.1:4000/integrate-external-ticketing-system","title":null,"content":""},{"relativeUrl":"/import-nodes-using-csv-files","url":"http://127.0.0.1:4000/import-nodes-using-csv-files","title":"Import nodes from CSV files","content":"For users who need to create many Nodes, we recommend using the CSV import rather than creating one at the time from the Node page. Alternately, users can also use the microServiceBus.com© API, which is not going to be covered in this article. To use the import file feature, it’s important that the file follows a specific format which is covered in the next section. Once the file is imported and validated, it is sent of for processing. This step might take a few minutes depending on the number of records in the file. When the process is completed, all users will get notified in the portal and an email is sent to the user who initiated the import.\nWhen your file is ready to be imported, you can import it from the Nodes page by clicking the CREATE NODE drop-down button at the top, and then select the Import from CSV option. The format must align with the following:"},{"relativeUrl":"/meter-configuration","url":"http://127.0.0.1:4000/meter-configuration","title":"Working with meter configuration","content":"Assigning individual configuration to Nodes is an important aspect of IoT as Nodes may be integrating with different meters, sensors and other equipment from one site to another. Even if they are connected to the same kind of equipment, connecting might require specific settings. Node `Meter Configuration’ allows you to create any number of specific settings that can be accessed from the Node and later used to connect, read and update meters. See also Working with Meter schemas for a better understanding of schemas and how you can customize them. As there are many different words describing similar things, there are a few commonly used terms that might be good to familiarize yourself with. Datasets define the meter connected to the Gateway. If you were to connect to an Modbus meter, the meter would be a Dataset. If on the other hand were connecting to a MBus meter, the sensors connected to the Mbus master would represent the Dataset. In cases such as Modbus, you may have any number of Datasets as other meters may be connected to the meter connected to the Gateway. In this case, each Dataset would have a Slave Id and Function. While a Dataset represents the meter or sensor, the Datapoint represents a value of interest. If you for instance, an MBus telegram may have any number of Data blocks, where each Data blocks represents a different reading such as Indoor temperature and Outdoor temperature. Each Data blocks is a Datapoint. Modbus meters have Registers which collectively holds many values. Each of those values is a Datapoint. Meter schemas defines the structure of the Meter Configuration and is tailored to serve a specific protocol. There are several schemas already available in microServiceBus.com, but you are free to create your own. Each schemas is devided into three top level sections: General information about the meter such as identifier, manufacturer and model The Connectivity section holds the necessary information about how we can connect to the meter such as Ip address or serial port See Datasets description above. Meter Configuration is available through the Action menu on the Nodes page or through the CTRL+R option by typing Select a type of meter from the drop list and click the ADD CONFIGURATION button. This will open the configuration dialog where you can set all the parameters. Saving the configuration, automatically updates the state of the Node. You can verify this by going to the properties page of the Node and click DEVICE STATE button. The desired section should have a msbConfig field with a URI pointing to the configuration. The Meter Configuration is available in the Node services using the following command:"},{"relativeUrl":"/migration-information","url":"http://127.0.0.1:4000/migration-information","title":"Migration information","content":"microServiceBus.com has been undergoing a migration which is coming close to general availability. The new release, scheduled for late May 2020, promises improved performance and scale, but also a platform allowing us to adapt new features at a much higher rate.\nEverything will work as normal part from two things: After the release has come available, you will be prompt to change your password. The reason for this is that we cannot read and migrate your password as your password information is not accessible to us. We still offer a free edition of microServiceBus.com, but we are no longer supporting the free IoT Hub. If you have a free IoT hub, you’ll need to migrate it to one from Microsoft, AWS or IBM. This process is simple and will provide you with more features and a more robust solution. Simply create a new IoT Hub, copy the connection information such as connection string or Access token depending on your choice of provider. Navigate to the Organization tab and click the SWITCH IOT PROVIDER button. Select you provider and click the CHANGE IOT PROVIDER button. All your existing Nodes will instantly be migrated to your new IoT Hub. First time using an IoT Hub? Check out the links below for more information:"},{"relativeUrl":"/node-installation-scripts","url":"http://127.0.0.1:4000/node-installation-scripts","title":"Node installation scripts","content":"Node installation scripts can optionally be used to install the microservicebus-node agent on a device. There are two versions of the scripts targeting Linux and Windows based devices. Running the scripts will install node.js if needed and proceed with downloading and installing the microservicebus-node agent. The scripts require a set of parameters which are generated at runtime, and are therefor not particularly useful to use outside the scope of creating a device. The content of the scripts can be downloaded here: Installation script for Linux Installation script for Windows"},{"relativeUrl":"/node-vpn-interfaces","url":"http://127.0.0.1:4000/node-vpn-interfaces","title":"Work with Node VPN interface and peers","content":"The microservicebus-node agent can be enabled to host or join a VPN network using WireGuard®. WireGuard® is a modern VPN that utilizes state-of-the-art cryptography. For more information about its supported protocols and cryptography. There are two main purposes for the Node VPN feature: There are scenarios where data is not transmitted to an IoT Hub endpoint, but to other locations using a none TLS or secure protocols. This can be the case when transmitting data to a local SCADA system using for instance IEC 60870-5-104. In such situations you can set up a secure tunnel for transport encryption. When Nodes are operating in a secure environment with no in- or outbound access to internet, a secondary Node can access as a “proxy” from a less secure zone. Before you begin, -WireGuard® needs to be installed on your gateway. You can follow the installation descriptions here to manually install it, or select one of our many Yocto images that comes with WireGuard® pre-installed. The private key is stored securely in Azure Key Vault, and once the key is generated it will only be accessible from the *Node after successful sign in.* Use the Post Up and Post Down fields if you for instance would like the host Node to forward traffic. For instance: The following example adds forwarding when VPN is started *The following example removes forwarding when VPN is shutdown * Please be careful when using forwarding! By default, the IPv4 policy in linux kernels disables support for IP forwarding. This prevents machines that run linux server from functioning as dedicated edge routers. To enable IP forwarding, use the following command: This configuration change is only valid for the current session; it does not persist beyond a reboot or network service restart. To permanently set IP forwarding, edit the /etc/sysctl.conf file as follows: Locate the following line: Edit it to read as follows: Use the following command to enable the change to the sysctl.conf file: If setting up a relay on a machine with multiple IP addresses (such as for a cloud-based VM), you need to specify which IP to use in the settings.json. You can do this by adding the following line on the top level of the file: If your Nodes are online, they should now fetch their respective VPN configurations and establish the connections. Their might be scenarios where you need to connect to the network using for instance your laptop. To do this begin by installing the WireGuard® VPN software from here. It is important to save this file in secure location as as it holds the private key Private keys are not stored in microServiceBus.com for User peers, so it’s important not too loose the file. But if you do loose it, remove the User peer and create a new one. To enable WireGguard logging: If a key get compromised you can re-generate the key by simply clicking the Generate button in the VPN tab. This will give the Node a new private key and update the public key of all Nodes on the network."},{"relativeUrl":"/reviewing-the-auditlog","url":"http://127.0.0.1:4000/reviewing-the-auditlog","title":"Reviewing the Audit log","content":"Audit logs can be used to find out who did what and when. All changes made to entities below are subject for auditing: The Audit logs are available by navigating to the Management page, and selecting the Audit logs tab. Or from individual entities by clicking the AUDIT LOGS button."},{"relativeUrl":"/roles-privilages-and-auditing","url":"http://127.0.0.1:4000/roles-privilages-and-auditing","title":"Roles, privilages and auditing","content":"Users can become members of an Organization by either creating the Organization or by being invited to the Organization by an owner. \nUser security and privileges are managed through Roles. Significant actions such as changing Organization settings or deleting a Node are subjects of Audit logging. microServiceBus.com comes with two roles; Owner and Co-administrator. As a rule of thumb, a Co-administrator can do everything except managing users and the Organization. Co-administrator are also prevented from Claiming Nodes, grant themself access to Nodes and use the remote terminal, although these privileges can be changed by an Owner. More informaiton about how to access Audit logs"},{"relativeUrl":"/run-background-services","url":"http://127.0.0.1:4000/run-background-services","title":"Run background services","content":"Background service is similar to an normal JavaScript or Python Services, but runs in the background independent of Flows and other services. A background service cannot interact with other services or transmit messages to the IoT Hub, but it lets you run background tasks such as checking disk space and other hardware related issues. You can set the Background service either through Node Templates or on the Node Property page. The script below checks that the disk space is not utilized to more than 75%. ```javascript\nconst fs = require(‘fs’);\nconst {exec} = require(‘child_process’);\nvar lastReported = 0; var exports = module.exports = {\n Start: function () {\n self = this;"},{"relativeUrl":"/services-and-scripts-in-microservicebus-in-depth","url":"http://127.0.0.1:4000/services-and-scripts-in-microservicebus-in-depth","title":"Services and Scripts in microServiceBus.com in depth","content":"This page is dedicated to those with a bit of prior knowledge regarding how flows and services in microServiceBus.com works. If you are not familiar with these concepts yet, please visit the Getting started first. When you as a developer is writing a service to use in a flow, you are extending the microservice object microServiceBus.com is exposing. This object has a number of functions and properties that could help you develop your code. First we will go through what is required in your own service, then what is available to you and lastly som best practices. Start() This function will be called when your node starts and your service has been downloaded. @parameters : none @returns : void @example Tip!\nHere it is great to add all your NPM packages. Stop() This function will be called when you disable or restart your node. @parameters : none @returns : void @example Tip!\nHere it is recommended to stop your timers or clear your processes. Process() This function will be called when you send messages from another service to this @parameters : message , context @returns : void @example Tip!\nHere is where you can integrate your services to share data with each other. Tip!\nThese are just some examples of properties you can access. Check the source code at GitHub to find more. Search for new MicroService ;) this.GetCurrentState() Returns the “device twin” or “shadow” of the device from the connected IoT Hub. @parameters : none @returns : Object @example this.AddNpmPackage(npmPackages, logOutput, callback) Downloads the packages in run time and calls the callback when download and installation is completed @parameters : npmPackages (string), logOutput (Boolean), callback (function) @returns : Void @example this.SubmitMessage(msg, format, headers) Creates a new context and sends the message to the next service in the flow in a specified format with or without headers. @parameters : msg (object or binary), format (string), headers (needs to be formatted as following : [{Variable : “[key]”, Value : “[value]”}]) @returns : Void @example this.SubmitResponseMessage(msg, context, contentType) Similar to SubmitMessage but is using the same context. Most often used for Internal- and Outboud services @parameters : msg (object or binary), context (including itinerary and variables), contentType (E.g. ‘application/json’) @returns : Void @example this.Configuration() Used to retrieve Meter Configuration. See Working with meter configuration @parameters : None @returns : All Meter configuration for the Node @example this.GetLocalTime() Used to get local time depending on location set on the Node (Properties page of Node)\n@parameters : None @returns : DateTime @example this.GetInstanceOf(serviceName, callback) Returns the service instance by name. This can be usefull when you have a service that needs to run as a singleton and server multiple services. For instance, if you connect to two or more RTU meters using the same serial port you might have to run the in sequense. In such case you might want to use an Modbus Master service as a singleton to access the actual meter while multiple other services are doing the request. @parameters : serviceName (name of service), callback (err, instance)) @returns : DateTime @example this.SetCronInterval(callback, cronExp) Returns a CRON job which will trigger on interval. @parameters : callback (function that will trigger), cronExp (CRON Expression)) @returns : CRON job @example this.SetCronInterval(cronJob) Stops the CRON interval. @parameters : cronJob (instance of CRON job)) @returns : void @example"},{"relativeUrl":"/site-verification","url":"http://127.0.0.1:4000/site-verification","title":"Site verification","content":"Arguably, one of the biggest challenges when rolling out new solutions, is the on-site installation and setup. Mounting a gateway and getting it connected to the cloud is often a minor part of the complete installation. Lots of wires, meters and other equipment might be required, and it’s vital that everything is connected before the on-site engineer leaves the premises and call it a day. The solution to this is to create a Site Verification test, and let the on-site engineer run the test(s) to verify it’s all up and running. Site verification test is nothing but a normal unit test. If you have ever written a unit test before, this should be really easy. If not, don’t panic. The Test-Driven Development pattern is very easy to understand. The Site Verification Test is using mocha which comes preinstalled for you Node. Writing a verification tests are just like writing a normal Service. In the microServiceBus.com portal navigate to Scripts & Services using the navigation menu. Click the CREATE NEW button. Set a name, filename and description. Before you hit the CREATE button, select Test file in the Service type drop-down list. In many scenarios you need the site engineer to be able to provide input to the test, such as which serial port or IP address to use. As with normal Services, add your parameters in the Static Properties tab. Make sure to use well descriptive names as these properties are going to be presented in the Site Verification Application Inside your test script, you can access these properties using the following syntax: Every test case file follows the same basic pattern. First, you have a describe block: describe is used to group individual tests. The first parameter should indicate what we’re testing — in this case, we’re going to make sure we’re connected to a meter, as we’ve passed in the string ‘Meter connection’. Secondly, inside the describe, we’ll have it blocks: it is used to create the actual tests. The first parameter to it should provide a human-readable description of the test. For example, we can read the above as “should be a valid IP address”, which is a good description of what we expect. The code to implement the test is then written inside the function passed to it. All Mocha tests are built from these same building blocks, and they follow this same basic pattern. To validate the IP Address, we can use a Regular expression, and test it with the IP Address parameter provided by the site engineer: Your test can have any number if if blocks! Before you can run the test on the Node you need to set the Node in “Test mode”. Navigate to the Node page and select properties from the Action menu. On the Node properties page, set the Mode to “Test mode”. Also click the Identities tab on the top and copy the serial number (set it if empty). Last, save the changes. On the Save confirmation dialog, click the “VIEW QR CODE” button. User your phone to navigate to the site verification app. Follow the instructions on the screen to verify the installation."},{"relativeUrl":"/using-node-terminal","url":"http://127.0.0.1:4000/using-node-terminal","title":"Using the Node terminal","content":"The Node terminal gives users a remote ssh session to the Node. This can be very helpful in times where you need full control of the gateway. The Node terminal is only available to Organization Owners, and can be accessed either through the ACTION menu on the Node page or by hitting CTRL+R and type: As you open the terminal, you are logged in as the same user as the microservicebus-node service is running with. Depending on your setup, this might only give you limited privileges. Also, the back-end of the terminal is hosted by microservicebus-node process. If you kill this process, -you terminate the terminal session."},{"relativeUrl":"/using-the-editor","url":"http://127.0.0.1:4000/using-the-editor","title":"Default keyboard shortcuts","content":"microServiceBus.com uses a Script/Service editor that provides the features and performance of today’s native editors, such as syntax highlighting for over a hundred languages, selecting from several themes, code folding, an API, and much more. Refer to this section for tips to improve your experience using the Script/Service editor."},{"relativeUrl":"/working-with-service-properties","url":"http://127.0.0.1:4000/working-with-service-properties","title":"Working with service properties","content":"The service property window is where you define the characteristics of your service. All properties are divided into three categories; General, Static and Security properties. While Static and Security properties are specific to each micro service, the General properties are generic and applies to all services. Most properties can be set using dynamic expressions. For instance, the sample below shows Static properties for the File outbound service. While the Path property is staticly set, the File name property is set to %guid%. This is called a Marco, and is unique to certain services. For the File outbound service, this means the name is going to get a unique name. Sometimes you might want to use some value from the payload to set a property. In such cases we use brackets. In the sample above we are transmitting an order with a property called orderid. You can combine two or more properties such as [firstName]_[lastName].json. You can also use context variables, in which case use curly brackets as above."},{"relativeUrl":"/what-is-a-node","url":"http://127.0.0.1:4000/what-is-a-node","title":"What is a Node?","content":"With an understanding of what a Micro Service is, it’s time to look at the Node. The Node is the agent running on your gateway or device. It is connected, owned and managed by an Organization. The Node is responsible for starting and stopping Flows and Services. -Essentially, the Node is where everything get processed. Every Service has a property called “Node”, which tells you where the Service is going to be executed, which could be any or all Nodes, regardless of location or platform. For instance, in the sample below we have a Flow, which describes the interchanges of the message. In this sample we have three Services; an Inbound FILE Service, a JavaScript Service and a Outbound Azure Send Event Service. These Services can all run on the same or on different Nodes. In the sample above, all Services are run on the same Node. When a file is save in a specific folder, the Inbound FILE Service will pick it up, create a Messages and pass it back to the Node orchestrator. The Node will attach the Flow definition to the Message and check to see if the next Service in line (the JavaScript Service in this case) is hosted on the same Node. If this is the case, as in our sample, the Service will just pass the Message to the next Service without ever leaving the Node. If Services are configured to be executed on different Nodes, the Node will send the Message to microServicebus.com, which in turn will re-direct the Message from the first Node to the Node hosting the next Service in line. To send a Message from one Node to the other as in the sample above, you’d need to enable the “Allow send” on properties window of the first Node. You access the Nodes properties through the Action button on each Node on the Nodes page, and there are many properties that might be important: Disconnect policies are very important, and dictates when a device is considered off-line and what action to take. Clicking the ENVIRONMENT button will present you with valuable information such as Networks, CPU, Memory and environment variables. Most IoT platforms respects the notion of State. Microsoft calls it Device Twin, whereas Amazon calls it Things Shadow. In both cases it is a JSON document that represents the State of the Node. Click the DEVICE STATE button to review and change the State. See the Reviewing the Audit log section. By clicking the RETRIEVE SYSLOG button a call is sent to the Node to compress and submit syslogs to the portal. These logs can be downloaded from the Logs tab. Nodes are running on the Node.js platform, and as such is supported on every platform node.js is working on, which luckily is most of them. For more information about Node.js, please visit nodejs.org"},{"relativeUrl":"/what-is-a-micro-Service","url":"http://127.0.0.1:4000/what-is-a-micro-Service","title":"What is a micro Service?","content":"A micro service is a part of a larger more complex solution, with a specific role. The service may be of different types where the most common types are: In microServiceBus a micro service is used in one or several flows. microServiceBus.com provides a large set of services out of the box, that you may use freely in your flows. Navigate to the main menu and select Scripts & Services. Click the button Create New and select In this example you're going to start from scratch with 'Create New'. Next, we’ll need to give the service a name, a description and select what kind of service. and press Create… In the new window (Edit Service Script) you can now: For now we’ll simply press Edit (top right) and edit our service template. We will only make a small modification to the template service and provide an additional JSON key/value “hello:World” and lower the trigger interval to every 5 second. Update the upper part of the service to match: Since we’re doing a minor change to the flow we’ll choose Update minor in drop-down to the botton right. Now, press Save and let’s celebrate your first custom service! :-) You now have the ‘MyGoodOldTimer’ service avaliable in the Toolbox, when modeling your flow (see below)! Continue on to how flows work to realise logic Introduction to flows Documentation in more depth on writing scripts can be found at Microservices in depth"},{"relativeUrl":"/what-is-a-flow","url":"http://127.0.0.1:4000/what-is-a-flow","title":"What is a Flow?","content":"Flows are entities responsible for orchestrating the execution of Services. Each instance of a flow, sometimes referred to as a Itinerary, holds state of all Services, Variables and Messages. While Variables and Messages may change over the lifetime of the Flow, the structure remains immutable, meaning once started, -Services and their related connections will not change although updated in the portal. You create Flows by going to the Flow page using the menu or by using the short-key CTRL+R and type “flow”. Clicking the “Create new” button on the top of the page takes you to the a page where give your flow a name and description. Clicking the “Create” button takes you to the Flow details page, and will present you with the Flow designer: The Flow designer is made up of two parts; the toolbox and the designer. The toolbox shows all the Services created in your organization and Services that belongs to the Root organization which is not directly accessible to you, other than you have access to all its Services. As you might remember from the What is a Service? section, there are different kind of Services. Only three kind of Services are visible in the toolbox. Inbound Services starts the Flow. These Services will always create the Message along with the context. Inbound Services are often triggered on an interval or event such as reading a Modbus register every minute. Outbound Services receives Messages from Inbound- or Internal Services and are used to control meters and devices or transmitting Messages to IoT Hubs for example. Internal Services are generally used to manipulate Messages or Variables, such as transforming, batching or compressing Messages. Each instance of a flow (itinerary) has ONE Message which might change over the course of the lifetime of the itinerary. Messages are often a JavaScript object but does not have to. Connecting two Services instructs the orchestrator to pass the execution from one Service to the other. The default routing condition is ‘true’, meaning the Message will always take this route. However, you can set the routing condition by double-clicking the connection and set the route variable. Eg. Setting this condition means only route Messages to the destination if the temperature is more than 30 degrees. Variables are available through the the whole execution of the itinerary and can be read or updated. However, you need to create them prior to using them. Click the “VARIABLES” button at the bottom to add variables."},{"relativeUrl":"/what-is-a-flow#variables","url":"http://127.0.0.1:4000/what-is-a-flow#variables","title":"What is a Flow?","content":"Flows are entities responsible for orchestrating the execution of Services. Each instance of a flow, sometimes referred to as a Itinerary, holds state of all Services, Variables and Messages. While Variables and Messages may change over the lifetime of the Flow, the structure remains immutable, meaning once started, -Services and their related connections will not change although updated in the portal. You create Flows by going to the Flow page using the menu or by using the short-key CTRL+R and type “flow”. Clicking the “Create new” button on the top of the page takes you to the a page where give your flow a name and description. Clicking the “Create” button takes you to the Flow details page, and will present you with the Flow designer: The Flow designer is made up of two parts; the toolbox and the designer. The toolbox shows all the Services created in your organization and Services that belongs to the Root organization which is not directly accessible to you, other than you have access to all its Services. As you might remember from the What is a Service? section, there are different kind of Services. Only three kind of Services are visible in the toolbox. Inbound Services starts the Flow. These Services will always create the Message along with the context. Inbound Services are often triggered on an interval or event such as reading a Modbus register every minute. Outbound Services receives Messages from Inbound- or Internal Services and are used to control meters and devices or transmitting Messages to IoT Hubs for example. Internal Services are generally used to manipulate Messages or Variables, such as transforming, batching or compressing Messages. Each instance of a flow (itinerary) has ONE Message which might change over the course of the lifetime of the itinerary. Messages are often a JavaScript object but does not have to. Connecting two Services instructs the orchestrator to pass the execution from one Service to the other. The default routing condition is ‘true’, meaning the Message will always take this route. However, you can set the routing condition by double-clicking the connection and set the route variable. Eg. Setting this condition means only route Messages to the destination if the temperature is more than 30 degrees. Variables are available through the the whole execution of the itinerary and can be read or updated. However, you need to create them prior to using them. Click the “VARIABLES” button at the bottom to add variables."},{"relativeUrl":"/what-is-a-flow#message","url":"http://127.0.0.1:4000/what-is-a-flow#message","title":"What is a Flow?","content":"Flows are entities responsible for orchestrating the execution of Services. Each instance of a flow, sometimes referred to as a Itinerary, holds state of all Services, Variables and Messages. While Variables and Messages may change over the lifetime of the Flow, the structure remains immutable, meaning once started, -Services and their related connections will not change although updated in the portal. You create Flows by going to the Flow page using the menu or by using the short-key CTRL+R and type “flow”. Clicking the “Create new” button on the top of the page takes you to the a page where give your flow a name and description. Clicking the “Create” button takes you to the Flow details page, and will present you with the Flow designer: The Flow designer is made up of two parts; the toolbox and the designer. The toolbox shows all the Services created in your organization and Services that belongs to the Root organization which is not directly accessible to you, other than you have access to all its Services. As you might remember from the What is a Service? section, there are different kind of Services. Only three kind of Services are visible in the toolbox. Inbound Services starts the Flow. These Services will always create the Message along with the context. Inbound Services are often triggered on an interval or event such as reading a Modbus register every minute. Outbound Services receives Messages from Inbound- or Internal Services and are used to control meters and devices or transmitting Messages to IoT Hubs for example. Internal Services are generally used to manipulate Messages or Variables, such as transforming, batching or compressing Messages. Each instance of a flow (itinerary) has ONE Message which might change over the course of the lifetime of the itinerary. Messages are often a JavaScript object but does not have to. Connecting two Services instructs the orchestrator to pass the execution from one Service to the other. The default routing condition is ‘true’, meaning the Message will always take this route. However, you can set the routing condition by double-clicking the connection and set the route variable. Eg. Setting this condition means only route Messages to the destination if the temperature is more than 30 degrees. Variables are available through the the whole execution of the itinerary and can be read or updated. However, you need to create them prior to using them. Click the “VARIABLES” button at the bottom to add variables."},{"relativeUrl":"/what-is-a-micro-service","url":"http://127.0.0.1:4000/what-is-a-micro-service","title":"What is a micro Service?","content":"A micro service is a part of a larger more complex solution, with a specific role. The service may be of different types where the most common types are: In microServiceBus a micro service is used in one or several flows. microServiceBus.com provides a large set of services out of the box, that you may use freely in your flows. Navigate to the main menu and select Scripts & Services. Click the button Create New and select In this example you're going to start from scratch with 'Create New'. Next, we’ll need to give the service a name, a description and select what kind of service. and press Create… In the new window (Edit Service Script) you can now: For now we’ll simply press Edit (top right) and edit our service template. We will only make a small modification to the template service and provide an additional JSON key/value “hello:World” and lower the trigger interval to every 5 second. Update the upper part of the service to match: Since we’re doing a minor change to the flow we’ll choose Update minor in drop-down to the botton right. Now, press Save and let’s celebrate your first custom service! :-) You now have the ‘MyGoodOldTimer’ service avaliable in the Toolbox, when modeling your flow (see below)! Continue on to how flows work to realise logic Introduction to flows Documentation in more depth on writing scripts can be found at Microservices in depth"},{"relativeUrl":"/getting-started","url":"http://127.0.0.1:4000/getting-started","title":null,"content":""},{"relativeUrl":"/what-is-an-organization","url":"http://127.0.0.1:4000/what-is-an-organization","title":"What is an Organization?","content":"Organizations separates ownership of artefacts (see Flows, Services and Nodes). This is also where you manage users and integration with ServiceNow, Cisco Jasper, Azure DevOps, GitHub and more. There are two roles within your organization; Owners and Co-Admins. Only owners can do user administration and moving nodes between organizations. To add a user to your organization, go to the Organization page and click the “ADD CO-ADMIN” button. Provide the email address of the person you’d like to invite. The invited person will then get an email with instructions of how to register and join the organization. If the invited person already have an account, he or she can go the the Organization page of any organization to accept the invite. ADFS is a standards-based service that allows the secure sharing of identity information between trusted business partners (known as a federation) across domains. The ADFS integration allows for people in your organization to authenticate themselves using your organization’s ADFS. By setting up integration with ADFS you’re essentially telling microServiceBus.com to trust your domain. Should you prefer having users signing in with an Active Directory account, you can provide necessary settings on the Organization page. For more information:"},{"relativeUrl":"/working-with-external-source-code-providers","url":"http://127.0.0.1:4000/working-with-external-source-code-providers","title":"Working with external source code providers","content":"Although microServiceBus.com come with version control, you might consider using tools you’re already familiar with such as GitHub or Azure DevOps. GitHub and Azure Devops integrations are done on Organization level. It might therefor be more convinient to bind the source code provider to the ROOT Organization as all Scripts and Services will then become available for all other Organizations Tip of the day: Unless you want to keep your Scripts and Services in a separate repo, create a directory in your source control for all mSB files. This action will create GitHub Webhooks which will be available in your GitHub repo under Settings/Webhooks. This action will create Service hooks which will be available in your Project under Service hooks."},{"relativeUrl":"/active-directory-integration-single-sign-on","url":"http://127.0.0.1:4000/active-directory-integration-single-sign-on","title":"Active Directory integration (Single Sign On)","content":"Through the Active Directory feature you can bring your own identity provider allowing your users a single sign one experience. Federated identity allows authorized users to access multiple applications and domains using a single set of credentials. It links a user’s identity across multiple identity management systems so they can access different applications securely and efficiently. When organizations implement federated identity solutions, their users can access web applications, partner websites, Active Directory, and other applications without logging in separately every time. Federated identity – also known as Federated Identity Management (FIM) – works on the basis of mutual trust relationships between a Service Provider (SP) such as an application vendor and an external party or Identity Provider (IdP). The IdP creates and manages user credentials and the SP and IdP agree on an authentication process. Multiple SPs can participate in a federated identity agreement with a single IdP. The IdP has mutual trust agreements with all these organizations. Although you can integrate with Active Directory using ADFS, we recommend using Open Id as described below. Information about integration using ADFS is available here Finish by hitting the “SAVE” button IMPORTANT These settings will not have effect until the site is restarted. Please notify your microServiceBus.com contact."},{"relativeUrl":"/api-terms-of-use","url":"http://127.0.0.1:4000/api-terms-of-use","title":"microServiceBus.com API - TERM OF USE","content":"Last modified: April 10, 2019 Thank you for using microServiceBus.com APIs, other developer services, and associated software (collectively, “APIs”). By accessing or using our APIs, you are agreeing to the terms below. You will only access (or attempt to access) an API by the means described in the documentation of that API. AXIANS IoT Operations and microServiceBus.com sets and enforces limits on your use of the APIs (e.g. limiting the number of API requests that you may make or the number of users you may serve), in our sole discretion. You agree to, and will not attempt to circumvent, such limitations documented with each API. All API’s have a throttling limit of 4 calls per minute. Some API’s require Organizations to have an SLA such as the one filed under “DeviceManagement”. These API’s may not work for un-managed Organizations. For more information about how to use microServiceBus.com APIs."},{"relativeUrl":"/using-microservicebus-api","url":"http://127.0.0.1:4000/using-microservicebus-api","title":"Using microServiceBus API","content":"The microServiceBus API hosts many of the operations otherwise available through the UI, allowing other applications to interact with Nodes and Meters. In many cases, the API is used from the Business Operation allowing them to configure and interact with nodes, meters and sensors. Business Operation generally work more with configuration tasks, using tools provided elsewhere. microServiceBus.com API is a REST based API that can be called from any application. To use the API you need an API key which you can receive by navigating to the Account page (click your user account in the top right corner). On the Account page, click “API keys”. Enter your password and token expiration and hit the GET API KEY button. Copy the token, and navigate to the swagger page. Paste your token in the api_key field at the top of the field. Tip: To use the API from outside the swagger page, add the token to the Authorization header. Tip: It’s not recommended to use a normal user account as the API account. Instead create a user account for each service or application that will use the API. This way it’s easier to track and audit updates. The microServiceBus API is segmented into groups of entities:"},{"relativeUrl":"/integrate-sim-card-management","url":"http://127.0.0.1:4000/integrate-sim-card-management","title":"Integrate SIM card management","content":"Cisco Jasper is a powerful SIM card management tool where you can manage state and set up automation rules for your SIM cards. The integration with Cisco Jasper enables automatically on-boarding of new devices wit no effort part from powering on the device. For this provisioning process to work, you need to set up a two-way trust between microServiceBus.com and Cisco Jasper; one for Cisco Jasper to notify microServiceBus.com of newly activated devices (SIM cards) and one for microServiceBus.com to call Cisco Jasper to make changes of updates to the configuration. microServiceBus.com will also query Cisco Jasper to notify users when data plans are reaching their limits. To set up the Cisco Jasper integration, follow these tow steps: Although microServiceBus.com can call Cisco Jasper on behalf of any user, it’s always a good practice to use a dedicated user. This way it becomes clearly visible in Cisco Jasper in which context any changes has been done. Your microServiceBus.com Organization is now set to call the Cisco Jasper API. With these steps completed, SIM cards that gets activated will automatically trigger your automation rule which will cause Cisco Jasper to call microServiceBus.com to create the Node in both microServiceBus.com and your IoT Hub. Shortly after the Node gets online it should automatically receive credentials to log on to the IoT Hub."},{"relativeUrl":"/integrate-with-aad","url":"http://127.0.0.1:4000/integrate-with-aad","title":"Integrate with Azure Active Directory using ADFS","content":"Azure Active Directory The Azure Active Directory (Azure AD) enterprise identity service provides single sign-on and multi-factor authentication to help protect your users from 99.9 percent of cyber security attacks. Name – example: microServiceBus-AD-Integration Supported account types – Single tenant accounts. Provider: Name of your company Account domain: The suffix of your organizations emailaddresses (example: company.com) Metadata address: Paste the url copied from Azure Portal"},{"relativeUrl":"/integrate-with-iot-hub","url":"http://127.0.0.1:4000/integrate-with-iot-hub","title":"Integrate with IoT Hub","content":"An IoT hub is a cloud hosted platform responsible for all communications to- and from Nodes. Other on-prem or cloud based services which would benefit from interacting with the Nodes would do so through the IoT hub. microServiceBus.com support four different IoT hubs from Microsoft, Amazon, Google and IBM. Through this integration, devices and things can be fully managed far beyond what is provided out-of-the-box. Although IoT hubs in general provide the same basic functionality, the main difference would be what is behind the IoT hub, such as machine lerning, reporting and processing. Your choice of IoT hub would, in the majority of cases, depend on what you want to do with the data. Azure IoT Hub - Enable highly secure and reliable communication between your Internet of Things (IoT) application and the devices it manages. Azure IoT Hub provides a cloud-hosted solution back end to connect virtually any device. Extend your solution from the cloud to the edge with per-device authentication, built-in device management, and scaled provisioning. Amazon AWS IoT - There are billions of devices in homes, factories, oil wells, hospitals, cars, and thousands of other places. With the proliferation of devices, you increasingly need solutions to connect them, and collect, store, and analyze device data. The Cloud IoT Owner privileges are required to browse the registry and manage devices. The downloaded project credentials file contains secure information. Store it in a safe place! Google IoT Core - Cloud IoT Core is a fully managed service that allows you to easily and securely connect, manage, and ingest data from millions of globally dispersed devices. Cloud IoT Core, in combination with other services on Cloud IoT platform, provides a complete solution for collecting, processing, analyzing, and visualizing IoT data in real time to support improved operational efficiency. IBM Watson IoT Platform - Securely connect, collect and start processing IoT data quickly and easily with Watson IoT™ Platform. And because it uses IBM Cloud, your company can scale and adapt quickly to changing business needs without compromising security, privacy or risk levels. There are scenarios where an IoT hub is not required, or rather required for the microServiceBus Node. For instance, if you have already built a working solution and only require Device Management (OTA, logging, monitoring, vulnerability scan and control), -the “No IoT Hub” option might be best suited for you."},{"relativeUrl":"/working-with-schemas","url":"http://127.0.0.1:4000/working-with-schemas","title":"Working with Meter schemas","content":"Meter schemas are the definition of all properties and setting of meters. Meter schems are used when working with Meter Cconfiguration and can be cusomized to your needs. See also Working with meter configuration how the schemas are used on the Node When creating a Meter configuration, you select a schema aligned with your meter, such as Mbus TCP or Modbus RTU. You then proceed to add Datasets, Datapoints and Metadata. When you save your configuration, you have essentially added the configuration to your Node.\nServices running on your Node, such as Modbus master will read the configuration to access the meter/sensor and retrieve the data. The base structure of the schema is always the same. Hence, it needs to be generic. The table below explains some of these terminologies in the context of different types of meters and sensors: This is not the place to explain everything about schemas, but we will cover enough to get started. You should have a common knowledge about JSON before you get started.\nEvery section in the schema will have fields like: The sample above defines a meterinfo element with four properties; id, manufacturer, model and meterType *all of which are required. The JSON output would look something like this: The sampel above decsribes an element called metadata which is of type “array”. The “items” element defines the structure of the containing objects, which in turn can have their own fields as decribed above. Needless to say, -the easiest way to get started is to copy an existing schema and customize it to your need. The root element is always an “object” and defines the unique identifier ($id) which needs to be unique throughout all schemas in the microServiceBus.com instance. The name and description is shown in the drop-box when the user selects the schema. There are five mandatory sections of a schema: There are some meters of similar kind such as MBus TCP, MBus RTU W-Mbus. These are all similar and would also share the same $baseType (“MBUS”). Related to the sample above, this could be “Modbus TCP” for example. The meterinfo section is metadata about the meter and would always look the same:\n| Field | Description |\n| ————– |————-|\n| id | A unique identifier of the meter | \n| meterType | E.g. Energy meter | \n| manufacturer | E.g. Elvaco | \n| model | E.g. CMeX50 | The connectivity section needs to be customized to provide all properties needed to connect to the device The datasets section needs to be customized to provide all properties needed to read the device The datasets section needs to be customized to provide all properties needed filter the telegram The metadata section should not be changed and gives the user the option of adding additional information."},{"relativeUrl":"/microservicebus-release-management","url":"http://127.0.0.1:4000/microservicebus-release-management","title":"microServiceBus.com release management","content":"microServiceBus.com (portal) along with agent packages; microServiceBus-node and microServiceBus-core are normally release as: New releases of the public portal (https://microServiceBus.com) are initially released to the developing environment (DEV) dev.microServiceBus.com, which is publicly available with no connection to the production data. This environment is predominantly used for developing and integration testing. Once testing is complete, changes are replicated to the STAGE environment (stage.microServiceBus.com). This environment is connected to the same data source as the production environment and should be used for acceptance testing. When code is submitted to the STAGE branch, ALL stage environments are affected including private and self-hosted, environments. Once acceptance testing is complete, PROD and STAGE environment are “swapped”, meaning IP addresses of https://microServiceBus.com and https://stage.microServiceBus.com are swapped leaving the STAGE environment in “last working state” and can be used as backup should issues be found in a later state. The process of swapping PROD and STAGE for private and self-hosted environments are done upon acceptance of the customer. It is however recommended to update at least once a month. Depending on the underlying architecture of the hardware, updates of the mSB-node can be handled differently. If, for instance, the mSB-node package is running in a Ubuntu Snap or a Docker container the updates of these packages are handled either manually or automatically along with the selected infrastructure. Should a customer want to have control over the releases of mSB-node, they can choose to fork the microServiceBus-node github repo and/or publish their forked repo as a custom npm package. Following this pattern, customer can choose when they decide when to publish new releases. Worth pointing out, that although this options gives the most control, it also requires a great deal of insight. Organizations can also control the version of microServiceBus-core using the settings on the Organization. The Node Version setting can be set to either latest, beta, ignore or a specific version. Normally, organizations would choose latest or a specific version for their production environment, however if you’d like to test the beta version on one or a subset of nodes, you can tag the node with BETA on the property page of the node. Once your Flow are in production we recommend locking the version of each Service by opening the property window of each Service and check the “Lock to version” checkbox. This will make sure the specific version of the Service is used, regardless of if it has been updated. Sometimes we need to test an update of a Service in production, while making sure other Nodes are still using the last stable version. This is common in scenarios where a Flow is used by many Nodes using tags. In such cases, a specific tag is applied to one or more nodes, such as “Amsterdam”, and rather than configuring a Service run on a specific Node, you’d use the tag instead (#Amsterdam). However, using tags this way will force all Nodes using the same version of the Service. -If you want to run one of the nodes on the latest version, you can apply the “BETA” tag to the node, in which case it will always ignore the “Lock to version” setting"},{"relativeUrl":"/controlling-nodes","url":"http://127.0.0.1:4000/controlling-nodes","title":"Controlling Nodes","content":"There are two recommended ways of restarting nodes. Navigate to the Nodes page, find the ACTION button for your Node then click restart Restarting a node by command Hit CTRL + R , and type restart [YOUR NODE] Example: restart node-00001 Will make the node to do a complete reboot of the system Will completely turn the system off and you will not be able to access the node unless you do a power cycle. Wiping the node will clear its settings! Moving a node to another organization will cause the Node to reconfigure, restart and join a new organiztion based on it’s IMEI identifier Sometimes it can be very useful to look back in time to find patterns of communication issues and other events. For this we have History data Historic data is not sent to microServiceBus.com, unless requested. The Audit log shows any action taken on Nodes Environment data refers to things like available memory and storage along with environment variables and CPU information."},{"relativeUrl":"/get-remote-access-to-your-nodes","url":"http://127.0.0.1:4000/get-remote-access-to-your-nodes","title":"Get remote access to your Nodes","content":"There are times when you might need to access your Nodes to dig through the local file system, check log files locally or just do some configuration of networks and services. SSH passwords is sufficient when you have a few Nodes, but imagine the hassle and the ensuing fight you will have with security when all of these passwords are stored on a file on your local computer. Or when you send a password to your collegue. Enter, SSH keys. By uploading the public part of your own SSH key to microServiceBus.com, you can get remote access to your Nodes. You will get your own user on the machine and therefore traceability on actions taken during your SSH sessions. Note!\nYou will need to have the snap microServiceBus-DAM installed to be able to add SSH keys to the device microServiceBus-dam is the device access manager that handles all the users, keys and secure transfers of these. To be able to get remote access to your device you will need to install the snap and link it to the microServiceBus-node snap. microServiceBus-dam is currently only available in a Ubuntu core environment. Install the snap with the following command: Navigate to your user page Manage user. Go to the tab SSH keys and either type in a username or have us generate one for you. These are case insensitive and will always have all lower-case characters. This will be the user that you use for your SSH session towards the Node. Refresh the page and navigate to the same tab. You can now add a SSH key that is linked to your user. If you do not have a SSH key you can create one by starting up a terminal on your computer and run: Add your device name and the public part of your key. You are now ready to request remote access to Nodes to be able to log in directly on the device. Navigate to the node page Nodes. Click on the Actions dropdown on the Node you would like to get access to and press on Grant Access. The Node will now fetch your public key and add it as a user on the device. The key will be removed after 3 hours for security reasons, so if you need more time than that you will have to Grant Access again. Once you have your public key uploaded and have Granted Access for yourself, you can now start a SSH sesssion from your device to the Node with the command: You can now do all of your operation, configuration and routing without having to worry about security and passwords ever again."},{"relativeUrl":"/groups-and-tags","url":"http://127.0.0.1:4000/groups-and-tags","title":"Grouping and tagging Nodes","content":"Tags are commonly used when you want to address an action on many Nodes such as when patching Nodes through the API, or as group when developing Flows that should run on multiple Nodes. Tags can be set on both Nodes and Flows. There are a few tags that are built-in such as #ALL and #BETA, but generally you’d create your own tags. For example, lets assume you create a flow that should read and transmit the current state of a heat pump. Lets also assume you’d be reading the values from the heat pump using Modbus. If every Node in your Organization is connected to a heat pump and you want the same Flow to execute an all Nodes, you would set the Node attribute of the first (inbound) Service to #ALL: The #ALL tags, as the name implies, causes the this Flow to run on all Nodes An other scenario would be where not all Nodes are connected to heat pumps, and you only want the flow to execute on a sub-set up Nodes within the Organization. It could also be that some of your Nodes are using a different manufacture of heat pumps, which in turn might require a different Flow/Service. In such cases, you’d be better off using a custom tag such as #NIBE-F2120: You can patch individual Nodes from the the Node page in the portal, but when you want to patch many Nodes, this approach is not efficient. In such cases you are better off using the API. For instance if you want to update the firmware on many Nodes you should use the Update Firmware API (/api/organizations/{id}/tags/{tag}/updatefirmware), where {id} is the Id of your Organization and the {tag} is the used to filter the Nodes. Again, if you want to update all the Nodes use the #ALL tag: While if you are a bit more cautious, you might consider rolling the update per region: The last sample assumes you have a number of Nodes with “BERLIN” tag set. Tags can be applied to Nodes from the Node Property page: You might also consider using the API: The majority of the Node is defined in a package called microservicebus-core, and you can set the preferred version at the Organization page. However, sometimes you might want to test one or two Nodes with the BETA release before updating all Nodes. To do this, you can tag the Node with #BETA or #EXPERIMENTAL. After restarting the Node the microservicebus-core component will update to BETA or EXPERIMENTAL release."},{"relativeUrl":"/managing-firmware-and-device","url":"http://127.0.0.1:4000/managing-firmware-and-device","title":"Managing firmware and devices","content":"The ability to update firmware’s or application containers is essential to secure your system. Device information refers to low-level components of your hardware, such as kernel, firmware, containers and other settings such as memory, storage and environment variables. All these can be accessed through a single view in on the Nodes page. From the Nodes page, click the ACTION button of any one of your online Nodes and select *Device. This will send a request to your Node and open the Device information dialog. The dialog presents four different tabs: This tab reveals common resources such as CPU, Memory and network, all to get a good overview of resource usage, but also a good place to find the IP address of your Node. Yocto based devises, usually comes with two or more kernel partitions. These are manage by a bootloader manager such as RAUC. The Device information dialog provides detailed information about each partition such as which is active, when it was activated and more. The Device information dialog also gives you the options of settings which partitions should be booted. You can also update the firmware from this dialog (also available using the microServiceBus API). If you are running Ubuntu Core or Ubuntu IoT, this is your go-to place for managing Snaps running on your device. The list gives you an overview of all installed Snaps and lets you refresh (update) them by clicking the REFRESH button. Keep in mind that updating Snaps may require rebooting the system. Although you can update your Snaps using this dialog, you may consider using the microServiceBus API to update more or all devices at once. Environment variables are a variables whose value is set outside the program, typically through functionality built into the operating system or microservice. An environment variable is made up of a name/value pair, and any number may be created and available for reference at a point in time. Configuring your system using bash scripts is a powerful and easy way to make sure consistency and integrity of your system is kept. Bash scripts are created just as you create a microservice, but make sure to Service type of your script to Patch script, as it will otherwise not be visible in the Device information dialog. With the Patch script created, you can select it in the drop-down list, and click the EXECUTE button to have the script executed on the gateway."},{"relativeUrl":"/provitioning-of-nodes","url":"http://127.0.0.1:4000/provitioning-of-nodes","title":"On-boarding and provisioning of new devices","content":"There are three supported ways you can provision devices: Once you have installed a Node and are ready to start it up, you can do so using a temporarily verification code which you can get from the Nodes page. The code is valid for 30 minutes and can be used as follows: The code and the Node name are only required the first time you start the node Node. Once provisioned, you can start it using only: For more information about how to install a Node Anonymous signin means the Node registers it self to be claimed in the microServiceBus.com portal. This action require either a Site manager role in multitennant environments such as microServiceBus.com, or Owner of an Organization in a Private- or Self hosted environment. Start the Node using only start: When claiming the node, it will be given whatever name you choose. By default it will be part of your current Organization, but you may change to any other Organization you are Owner of. IMPORTANT! Provisioning a Node using anonymous signin will send device information such as IP and MAC addresses to the microServiceBus.com portal (for identifying which Node to claim). If the MAC address is whitelisted (see Using MAC whitelist section below) the MAC whitelist option will surpass the Claim option and the Node will get automaticly provisioned (provided it has not been used before). The media access control address (MAC address) of a device is a unique identifier assigned to a network interface controller (NIC). Each device has it’s own unique MAC address, and you can register these addresses in microServiceBus.com to simplify the on-boarding of devices in bulk. Once a device has been provisioned using the MAC address, the address is consumed and can not be used again. It’s recommended only to register devices that you are planning to provision at a specific point in time. Keep in mind that MAC addresses can be spoofed. Follow the steps below to on-board devices using MAC addresses The International Mobile Equipment Identity or IMEI is a unique number to identify the modem of the device. Before provisioning devices using the SIM card id, you need to integrate your organization with Cisco Jasper. To setup the Cisco Jasper integration, follow this guide. Once integrated, you can start the Node using only the –imei:"},{"relativeUrl":"/user-management","url":"http://127.0.0.1:4000/user-management","title":"User management","content":"Sharing is caring, and that goes for your organizations as well. Time to go through different user scenarios for your organizations. There are two roles within your organization; Owners and Co-Admins. Only owners are authorized to do user administration and moving nodes between organizations. To add a user to your organization, go to the Organization page and click the “ADD CO-ADMIN” button. Provide the email address of the person you’d like to invite. The invited person will then get an email with instructions of how to register and join the organization. If the invited person already has an account, he or she can go the Organization page of any organization to accept the invite. Note in the picture above that once you have added a Co-Admin to your organization you now have the option to assign the Owner role to that user. You need to be owner of an organization to assign the owner role. Once you have assigned the owner role to a user it can’t be reverted by you, only the user in question can remove the role assigned to them. ADFS is a standards-based service that allows the secure sharing of identity information between trusted business partners (known as a federation) across domains. The ADFS integration allows people in your organization to authenticate themselves using your organization’s ADFS. By setting up integration with ADFS you’re essentially telling microServiceBus.com to trust your domain. Should you prefer having users sign in with an Active Directory account, you can provide necessary settings on the Organization page. Once you have clicked the Edit button on the Organization page you will have to edit these fields: Once the correct information is applied, you should be able to login with your Active Directory account. Don’t forget to invite your Active Directory account before you try to login with it."},{"relativeUrl":"/working-with-alerts","url":"http://127.0.0.1:4000/working-with-alerts","title":"Working with Alerts","content":"Managing and taking actions on Alerts is a crucial part of IoT Device Management and allows you to react to events such as notifying a technician to replace a sensor if the battery is low or send a text message if the pressure of the heat pump is running high. There are several built-in Alerts and you can also configure your own. Alerts are only available on managed Organizations and can be enabled on the Organization page. An Alert can be created from anywhere but most commonly from a Node and is commonly some abnormality you’d like to take action on. All incidents have an identifier (error code), a description and an action. Actions are described in detail below. A Custom Alert is implemented using three parts: The identifier (error code), description and an action. Navigate to the Organization page, and scroll down to the ServiceNow section. If your organization is managed, the MANAGE ALERTS button is enabled. Click the button to open the Manage Alert dialog. By default, there should be two policies already created for you; Unhanded Exceptions and Offline Nodes. These are described in detail in the Default policies section below.\nClick the Add new record button on top to create a new row in the table. Set a Error code and describe the Alert. Finally, select an Action and set the parameters. \nPlease note that you can have multiple actions on the same Error code. The * Send issue email* action sends an hourly aggregated notification of all incidents to participants you’ve configured clicking the Params button (…). The to element can hold a comma separated list of email addresses who subscribes to this event. Similar to the * Send issue email* action, this action sends an hourly notification to participants you’ve configured clicking the Params button (…). Sample The Call API will send a POST request of every incident to a REST service of your choice. Configure the parameters as the table below: Using bearer token Using custom header The Create ticket action will create an Alert in ServiceNow and does not require any parameters. This action is part for the Unhanded Exception (error code 90000) default policy. When Nodes come offline a workflow will be triggered which does the following:"},{"relativeUrl":"/gettingStarted-list","url":"http://127.0.0.1:4000/gettingStarted-list","title":null,"content":""},{"relativeUrl":"/quickreference-list","url":"http://127.0.0.1:4000/quickreference-list","title":null,"content":""},{"relativeUrl":"/news","url":"http://127.0.0.1:4000/news","title":"News","content":"Although there has been several small fixes in this release, this update is to align microServiceBus.com with underlying platforms and dependancies. IMPORTANT! Due to changes in .Net 8, API keys needs to be regenerated. Our support team will contact you and assist you if needed. microServiceBus.com will be undergoing a migration to .net 8 in November, whilst this update primarly focus on simplyfying the deployment in November/December. This includes refactoring of configuration settings, security updates and bringing all dependancies to latest version. Changes in microservicebus-core mentioned below has been available for testing since May 2022. All Nodes using “latest” will automaticly be updated once restarted. If you have not yet tested the BETA version and don’t want this update at this moment, navigate to the Organization page, click EDIT on the NPM feature and set the “Default version” to 3.16.1. THIS CHANGE WILL BE APPLIED 31 st of Aug (tomorrow) As summer and vacations are coming to Sweden we’re planning on doing some re-factoring and aligning our products with the latest platforms and frameworks. microServiceBus.com (portal) will be migrated to .net6, microservicebus-node to Node.js 16+ and our Yocto images to Kirkstone. We expect all of this to be ready by Jul-Aug and we will freaze the backlog until then. The new Python based Node is intended for smaller devices or where Node.js is not working. It comes with some limitation in comparison to mSB-node (Node.js), but is still a very manageable alternative. Enable / Disable node with CTRL+R creates multiple services on node #535 Prevent Unauthenticated SignalR calls from nodes\nAll calls from Nodes are authenticated directly on connection rather than only using SignIn method. Mobile console\nThe *Console has been extended to the mobile view History log of all successful and failed transmitted messages along with related events.\nFrom the Node page users can now access last weeks event Action drop-down menu. This will provide good insight of everything happening on the node. Highlighting in Console\nAlong with filtering users are now able to highlight events of interest. GitHub integration\nYou can now synchronize Scripts in your microServiceBus.com organization with your gitHub Repo! Just follow this simple guide to Integreate with GitHub. Aggregations of this information can be accessed from the portal. Azure device sdk (azure-iot-device-*) has been updated to 1.4.0.\n1.4.0 comes with many updates and improvements for handling re-connect and persistence of messages. Allow ‘node restore’ with parameter specifying customer’s (private) environment uri.\nWhen starting up the node for the first time you can now use -env to specify private or self hosted hubs: Always persist messages on Node \nBy setting the retention period on the Node greater than \n“0”, all outgoing event and messages are persisted on the device until the retention period is exceeded or the available storage is less than 25%. Fixes: Implement retry policy “NoRetry” for Azure IoT. Migrated to 1.3.0 of for Azure device SDK."},{"relativeUrl":"/administrativetasks-list","url":"http://127.0.0.1:4000/administrativetasks-list","title":null,"content":""},{"relativeUrl":"/integration-list","url":"http://127.0.0.1:4000/integration-list","title":null,"content":""}] +[{"relativeUrl":"/what-is-msb","url":"http://127.0.0.1:4000/what-is-msb","title":"What is microServicebus.com?","content":"Ultimately, microServiceBus.com is designed fill the gap between the out-of-the box device management provided by vendors such as Microsoft, Amazon and IBM, and what is required by the enterprise. It aims to address common challenges in the industry of IoT, such as planning for change, steep learning curves and provisioning of new devices. microServiceBus.com is a platform based on agents, also known as Nodes, running on gateways and controlled from a portal known as microServiceBus.com. microServiceBus.com and all related products and services are owned by AXIANS IoT Operation and is part of VINCI-Energies On-boarding new devices is difficult at scale. Gateways need to automatically be assigned a cloud identity, receive keys and certificates. -All in a highly secure manner.\nmicroServiceBus.com provide a scalable, cross cloud vendor solution based either on integration with SIM card management tools like Cisco Jasper or MAC address white-listing. For more information: No part of any system will stand the test of time. Software is constantly updated to align with security threats or new required features.\nUpdates and patching are easily handled through microServiceBus.com by either replacing entire firmware or individual services. Updates can be done manually or scheduled through tasks. This can be done for single devices or groups of devices.\nEasy deployments to IoT devices facilitates Agile development! For more information: Source code and services are not only deployed to devices, but need to be audited and versioned to ensure the end-to-end business process.\nWith complete insight and traceability, code can be fully managed and versioned within the microServiceBus.com portal. However, we also integrate with Git repositories such as GitHub and Azure DevOps. For more information: Identifying and resolving problems can be a difficult mission in any system, but spread over many thousands of remotely located units brings it to a whole other level!\nmicroServiceBus.com provides great insight to what is and has happened on the device. Through it’s tracking capabilities, developers and operation staff can gain understanding of what is happening, and even remotely debugging the code, and instantly deploy fixes. For more information: microServiceBus.com extends to a complete Application Lifecycle Management system through its integration with 3rd party vendors, and continues to expand through its extensive API.\nAs of today, microServiceBus.com integrate with ServiceNow for Issue, problem- and release management, allowing customers to align their existing service desk and Nightly Operation Center (NOC). Integration with Cisco Jasper makes way for a compete SIM card management, along with GitHub, Azure DevOps, Active Directory and more. For more information:"},{"relativeUrl":"/installing-microservicebus-node","url":"http://127.0.0.1:4000/installing-microservicebus-node","title":"Installing microServiceBus-node","content":"microServiceBus-node is the agent that needs to run on your device, and requires node.js and npm to be install prior to installing the agent. Node.js® is a platform built on Chrome’s JavaScript runtime for easily building fast, scalable network applications. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient, perfect for data-intensive real-time applications that run across distributed devices. Node.js provides lost of useful scenarios outside the scope of microSeviceBus.com® and as such it can be used together with other applications and solutions deployed on Node.js. Along with Node.js comes npm, which is a package manager for Node.js along with other things. After installing Node.js, you can use npm to install the microServiceBus.node package, and from there, you’re pretty much set to get started. To complete this process, just follow these three steps: To install Node.js go to https://nodejs.org/download/ and download the installation media for your platform. Make sure you install the npm package manager as well. Download the latest stable version and install the msi using the default settings. This will install both Node.js and npm. Be aware that if you want to run microServiceBus-node as a daemon you need to install the agent as root! If you are on a Ubuntu or Debian operating system you simply open a terminal and use the following command: \nsudo apt-get update \nsudo apt-get install nodejs While there, continue to install npm using the following command: To make npm work on a Raspberry Pi you might need to set the registry to HTTP using this following command: For a fully manageable Raspberry Pi, consider using the Raspberry Pi Yocto Image for more info: Installing node on raspberryPi Open a terminal or command window and create a directory of your choice. Then type the following: This command creates and installs the package in a folder called node_modules. Browse to the node_modules/microservicebus-node folder. \nBefore you start your node, you need a temporary verification code which you can generate from the Node page. With the microServiceBus-node installed we need create the node in the microServiceBus.com portal. There are a number of ways to create and automatically provision nodes. For now, we’ll keep it simple and use the Nodes page. Navigate to the Nodes page and create a node using the CREATE NEW NODE button on the top. Give the node a name and description and hit CREATE. Back at the the Nodes, your new Node should be visible in the list. With the microServiceBus-node package installed and the Node created in the portal, it’s time to start the node. The first time you start the node, it has no knowledge of what organization it belongs to nor does it have any access keys to authenticate to microServiceBus.com or you IoT hub for that matter. There are many ways you can pre-configure the node before it’s started, but again we’ll keep it simple. On the Nodes page in the portal, click the GENERATE button. Copy the generated verification code and go back to your terminal or console. The verification code is unique and valid for 30 min, and can be used to configure a node.\nIn your terminal/console, type the following: This should start the Node, which should begin by downloading microServiceBus-core, which together with microServiceBus-node make up the agent that we generally refer to as “The Node”. The installation should complete after a couple of minutes, after which it will authenticate it self using the temporary verification token you generated before. In the final step before completion, the Node will install the necessary packages for communication with your IoT hub, after which you should see you *Node online in the portal. If you want to stop the Node, simply hit CTRL+C/CMD+C in the terminal/console. To start it up again, simply type: Step 1: Create A Unit File Open a sample unit file using the command as shown below: Step 2: Add in the following text : Step 3: Set permissions\nThe permission on the unit file needs to be set to 644 : Step 4: Configure systemd\nNow the unit file has been defined we can tell systemd to start it during the boot sequence:"},{"relativeUrl":"/running-microservicebus-node-on-a-yocto-image","url":"http://127.0.0.1:4000/running-microservicebus-node-on-a-yocto-image","title":"Running microServiceBus-node on a yocto image","content":"Yocto is an huge topic and to get you started we are going to setup an Raspberry Pi to run an custom pre built Yocto image. The pre built image contains 4 partitions with some key parts that enables microServiceBus.com to do remote firmware updates. If you have previous experiences with Yocto and only looking to include the microServiceBus agent to your build have a look at meta-microservicebus-node The boot partition contains the bootloader, in this case U-Boot. The bootloader is first to run after power up. U-Boot is responsible to load the Linux kernel into memory and decide if RootFS 1 or 2 should be mounted by the kernel. In the rootfs partitions all Linux user space software is installed. There is two rootfs partitions to be able to update and swap firmware, only one is active at a time. The software most interesting for us is microServiceBus-node and RAUC. microServiceBus-node is responsible for installing and updateing microServiceBus-core. microServiceBus-core will check for new firmware, if newer firmware exists microServiceBus-core will download firmware and then call RAUC to install and swap rootfs next boot. Data partition is used to store data that will be persistent between firmware updates. microServiceBus-node runs by “msb” user whose home directory is located under /data/home/msb. The microServiceBus agent stores scripts and data under the home directory by default. The Yocto Project is an open source collaboration project that helps developers create custom Linux-based systems regardless of the hardware architecture. Yocto build system runs on Linux but this tutorial will use pre build files and is targeted Windows as an host system. In this tutorial we will use target to reference the Raspberry Pi and host to reference the PC used to write the SD-card. Tip! For more info regarding Yocto please visit Yocto project This image use RAUC software to apply firmware updates. microServiceBus-node will download new firmware from mSB.com and call RAUC install over d-bus to trigger the update.\nRAUC use X.509 cryptography to sign the update bundles, in this tutorial the example bundles is signed using an demo key. Tip! For more info regarding RAUC please visit RAUC To follow along this tutorial you need some hardware. Here is some software that is good to download/install before moving on The Raspberry Pi setup use SSH-keys for authorization when connection with SSH from host. If you already have an public and private key pair you can skip this section. To create an SSH-key pair follow the steps below. Tip! If you have problem you can follow this guide This will erase all content on the SD-Card, backup any data before continuing! To add your public SSH-key to the Raspberry Pi image you need to create an authorized_keys file. An init script will copy your key to the active rootfs on boot, you can use an USB flash drive or place the file on the boot partition on the SD-card. Your file should look something like below: If you use cable to connect to LAN you can skip this section.\nAs the Raspberry Pi is intended to run headless(no display) and be able to swap rootfs without losing your WiFi settings an configuration file can be copied to the boot partition. An init script will copy your configuration file to the active rootfs on boot, you can use an USB flash drive or place the file on the boot partition on the SD-card. WPA-Supplicant is used to setup WiFi on the Raspberry Pi. WPA-Supplicant template for WPA and WPA2: Tip! For more info regarding WPA-Supplicant conf you can read here To start microServicebus-node on the Raspberry Pi an service file is used to auto start it and restart it in case of failure. There is an default service file on the SD-image already but you can add an custom service file to the boot partition to set different configurations for microServiceBus. We are going to use this to set sign in name and verification code. The default service file use white list and MAC address for sign in. An init script will copy your service file to the active rootfs on boot, you can use an USB flash drive or place the file on the boot partition on the SD-card. microServiceBus-node service template: At this stage you hopefully have an working SD-Card to use in your Raspberry Pi. If you like to see the boot process connect an HDMI display to your Raspberry Pi and an keyboard to be able to interact. But if all off the above configuration is correct your Raspberry Pi node should come online in mSB.com if it have internet access. An SSH-server is running on the Raspberry Pi by default and allow connections using SSH-key authentication. If your configuration above is correct the generated public SSH-key have been added to ~/.ssh/authorized_keys and will grant you access. If the address is empty the node may have been assigned an IP late or after fully booted, press enter to reprint the prompt. Default there is no root password, thus login local with keyboard is not possible. You need to authenticate with SSH-Key. Enter the Raspberry Pi address Now we have to select our private SSH-key, in the tree to the left open Connection->SSH->Auth, then browse your private key. Note, this password will not be permanent when you do firmware update later. Tip! If you have problem this guide may help When using Yocto and RAUC microServiceBus enable the possibility to do remote firmware updates. In this setup we will only update the rootfs but RAUC have the possibility to update kernel, data partitions or even the bootloader it the target hardware have support for it. Follow the steps bellow to upload and apply an new firmware to your target. In rootfs0 you should see “state”: “inactive” and in rootfs1 “state”: “booted, this indicates that your node now have booted to your new firmware on rootfs1 Back to home page: Home"},{"relativeUrl":"/common-commands","url":"http://127.0.0.1:4000/common-commands","title":"Common Linux terminal commands","content":"grep and awk sample vi or vim is a commonly used file editor, which can be complex to use, but here are a few commands to get you started. less is a great tool for analyzing log files. systemd is a software suite that provides an array of system components for Linux operating systems, such as daemons (services). systemctl is the tool you use to interact with systemd journalctl is also part of the systemd suite and helps you view logfile in real-time. journalctl -u [service] -n [number of previous lines] -f . E.g. E.g."},{"relativeUrl":"/get-insight-using-tracking","url":"http://127.0.0.1:4000/get-insight-using-tracking","title":"Get insight using tracking","content":"Though the Console can give you valuable understanding of the execution of your Services, it might not provide insight into your overall processes and messages. -This is where Tracking comes to the rescue. When enabling Tracking for a Node, the message along with its context for every executed Service will be transmitted to the Tracking database of microServiceBus.com. The data will be automatically deleted after 30 days, but is the single exception to storing content- (payload) and context data (meta data) in microServiceBus.com. Apart from this exception, sensor and meter data sent to the IoT Hub never passes microServiceBus.com. That being said, it’s a valuable tool when identifying and resolving issues. By default, Tracking is disabled, and you should always remember to disable it when your are done as Tracking will add extensively to your data usage. To enable the Tracking, navigate to the Nodes page, and simply toggle the Tracking button of the Node you’d like to work with. Navigate to the Management page using the menu, click the Tracking tab at the top. If your Node has executed any Services since you enabled Tracking you should see a list of events: Each line represents one execution of your Flow. Select one of the instances by clicking the View Details button. This takes you to a new window, showing a snapshot of the state after each Service executed. The first tab shows you where in the flow the snapshot was captured. The other tabs reveal any errors, what the payload (content) looks like but also variables and metadata (context)."},{"relativeUrl":"/using-the-console","url":"http://127.0.0.1:4000/using-the-console","title":"Using the Console","content":"microServiceBus.com comes with a Console feature which provides similar output as you’d have through a terminal. Enabling Console output is a very powerful and common way to debug your Service and Flow. It will provide you with insight of how your Services behave and any issues you might experience. By default, Console output is disabled, and you should always remember to disable it when your are done as Console output will add extensively to your data usage. To enable the Console output, navigate to the Nodes page, and simply toggle the Console button of the Node you’d like to work with. Without doing anything else, you will only see default output from the Node. To write your output from your Service, leave the Console window open, and open up a new window and navigate to the Service script and open the editor. To write to the Console output, use the Debug function as: Debug statements will work as console.log() and will always be visible in the terminal, however they will only be visible in the Console output if enabled in the portal. Similarly, you can also use the ThrowError function to track errors: Part from sending the exception information to the Console, the ThrowError function also submit tracking information, which can optionally be sent to Issue tracking systems like ServiceNow. The context parameter is optional, and only relevant if it exists such as in the Process function. Use an error number lower than 90000, as error code above are reserved for microServiceBus.com. To view the output, simply navigate to the Console in the portal. Tip: If other developers are using the Console at the same time as you, the output can be exhausting. -Use the filtering option and set it to the name of your Node."},{"relativeUrl":"/integrate-external-ticketing-system","url":"http://127.0.0.1:4000/integrate-external-ticketing-system","title":"Integrate external ticketing system (ServiceNow)","content":"ServiceNow was a software-as-a-service provider, providing technical management support, such as incident- asset- and license management, to the IT operations of large corporations, including providing help desk functionality. The company’s core business revolves around management of “incident, problem, and change” IT operational events. microServiceBus.com integrates with ServiceNow to delegate incidents to service desks and NOC’s (nightly operation center). ServiceNow also extends microServiceBus.com by providing automation capabilities for handling things like restarting Nodes. But more importantly ServiceNow really takes off where microServiceBus.com ends by escalating incidents to designated resources along with solid ITIL processes further extended to problem and release management. For better audit visibility, we recommend using a designated API user With the integration set up, all Nodes are represented as Configuration Items (CI’s) meaning any incident or problem will always be linked to the CI. This also gives you a great history view where you might find patterns of problems related to specific Nodes. By default, any Off-line node will be reported in ServiceNow as an incident together with any Unhandled exception. Off-line nodes however, will not get escalated until the connectivity has been verified again which by default happens ten minutes after the incident was reported. This is to mitigate Nodes that are connected using 2G/3G/LTE where short disconnected periods are common. Although it’s important to handle Off-line nodes, organizations often need to handle their own errors and exceptions. For instance, imagine a sensor reporting low battery or a heat pump reporting high pressure. These are not exceptions related to the platform, although it’s very important that such incidents gets escalated to ServiceNow. To handle custom issues, navigate to the Organization page, scroll down to the ServiceNow section and click the MANAGE INCIDENT POLICIES. As you can see in the list of Incident policies, you already have Unhandled Exceptions and Node is offline. If you’re calling this from a Process function, you may add the context variable as the first parameter."},{"relativeUrl":"/active-directory-integration-single-sign-on","url":"http://127.0.0.1:4000/active-directory-integration-single-sign-on","title":"Active Directory integration (Single Sign On)","content":"Through the Active Directory feature you can bring your own identity provider allowing your users a single sign one experience. Federated identity allows authorized users to access multiple applications and domains using a single set of credentials. It links a user’s identity across multiple identity management systems so they can access different applications securely and efficiently. When organizations implement federated identity solutions, their users can access web applications, partner websites, Active Directory, and other applications without logging in separately every time. Federated identity – also known as Federated Identity Management (FIM) – works on the basis of mutual trust relationships between a Service Provider (SP) such as an application vendor and an external party or Identity Provider (IdP). The IdP creates and manages user credentials and the SP and IdP agree on an authentication process. Multiple SPs can participate in a federated identity agreement with a single IdP. The IdP has mutual trust agreements with all these organizations. Although you can integrate with Active Directory using ADFS, we recommend using Open Id as described below. Information about integration using ADFS is available here Finish by hitting the “SAVE” button IMPORTANT These settings will not have effect until the site is restarted. Please notify your microServiceBus.com contact."},{"relativeUrl":"/api-terms-of-use","url":"http://127.0.0.1:4000/api-terms-of-use","title":"microServiceBus.com API - TERM OF USE","content":"Last modified: April 10, 2019 Thank you for using microServiceBus.com APIs, other developer services, and associated software (collectively, “APIs”). By accessing or using our APIs, you are agreeing to the terms below. You will only access (or attempt to access) an API by the means described in the documentation of that API. AXIANS IoT Operations and microServiceBus.com sets and enforces limits on your use of the APIs (e.g. limiting the number of API requests that you may make or the number of users you may serve), in our sole discretion. You agree to, and will not attempt to circumvent, such limitations documented with each API. All API’s have a throttling limit of 4 calls per minute. Some API’s require Organizations to have an SLA such as the one filed under “DeviceManagement”. These API’s may not work for un-managed Organizations. For more information about how to use microServiceBus.com APIs."},{"relativeUrl":"/using-microservicebus-api","url":"http://127.0.0.1:4000/using-microservicebus-api","title":"Using microServiceBus API","content":"The microServiceBus API hosts many of the operations otherwise available through the UI, allowing other applications to interact with Nodes and Meters. In many cases, the API is used from the Business Operation allowing them to configure and interact with nodes, meters and sensors. Business Operation generally work more with configuration tasks, using tools provided elsewhere. microServiceBus.com API is a REST based API that can be called from any application. To use the API you need an API key which you can receive by navigating to the Account page (click your user account in the top right corner). On the Account page, click “API keys”. Enter your password and token expiration and hit the GET API KEY button. Copy the token, and navigate to the swagger page. Paste your token in the api_key field at the top of the field. Tip: To use the API from outside the swagger page, add the token to the Authorization header. Tip: It’s not recommended to use a normal user account as the API account. Instead create a user account for each service or application that will use the API. This way it’s easier to track and audit updates. The microServiceBus API is segmented into groups of entities:"},{"relativeUrl":"/integrate-sim-card-management","url":"http://127.0.0.1:4000/integrate-sim-card-management","title":"Integrate SIM card management","content":"Cisco Jasper is a powerful SIM card management tool where you can manage state and set up automation rules for your SIM cards. The integration with Cisco Jasper enables automatically on-boarding of new devices wit no effort part from powering on the device. For this provisioning process to work, you need to set up a two-way trust between microServiceBus.com and Cisco Jasper; one for Cisco Jasper to notify microServiceBus.com of newly activated devices (SIM cards) and one for microServiceBus.com to call Cisco Jasper to make changes of updates to the configuration. microServiceBus.com will also query Cisco Jasper to notify users when data plans are reaching their limits. To set up the Cisco Jasper integration, follow these tow steps: Although microServiceBus.com can call Cisco Jasper on behalf of any user, it’s always a good practice to use a dedicated user. This way it becomes clearly visible in Cisco Jasper in which context any changes has been done. Your microServiceBus.com Organization is now set to call the Cisco Jasper API. With these steps completed, SIM cards that gets activated will automatically trigger your automation rule which will cause Cisco Jasper to call microServiceBus.com to create the Node in both microServiceBus.com and your IoT Hub. Shortly after the Node gets online it should automatically receive credentials to log on to the IoT Hub."},{"relativeUrl":"/integrate-with-aad","url":"http://127.0.0.1:4000/integrate-with-aad","title":"Integrate with Azure Active Directory using ADFS","content":"Azure Active Directory The Azure Active Directory (Azure AD) enterprise identity service provides single sign-on and multi-factor authentication to help protect your users from 99.9 percent of cyber security attacks. Name – example: microServiceBus-AD-Integration Supported account types – Single tenant accounts. Provider: Name of your company Account domain: The suffix of your organizations emailaddresses (example: company.com) Metadata address: Paste the url copied from Azure Portal"},{"relativeUrl":"/integrate-with-iot-hub","url":"http://127.0.0.1:4000/integrate-with-iot-hub","title":"Integrate with IoT Hub","content":"An IoT hub is a cloud hosted platform responsible for all communications to- and from Nodes. Other on-prem or cloud based services which would benefit from interacting with the Nodes would do so through the IoT hub. microServiceBus.com support four different IoT hubs from Microsoft, Amazon, Google and IBM. Through this integration, devices and things can be fully managed far beyond what is provided out-of-the-box. Although IoT hubs in general provide the same basic functionality, the main difference would be what is behind the IoT hub, such as machine lerning, reporting and processing. Your choice of IoT hub would, in the majority of cases, depend on what you want to do with the data. Azure IoT Hub - Enable highly secure and reliable communication between your Internet of Things (IoT) application and the devices it manages. Azure IoT Hub provides a cloud-hosted solution back end to connect virtually any device. Extend your solution from the cloud to the edge with per-device authentication, built-in device management, and scaled provisioning. Amazon AWS IoT - There are billions of devices in homes, factories, oil wells, hospitals, cars, and thousands of other places. With the proliferation of devices, you increasingly need solutions to connect them, and collect, store, and analyze device data. The Cloud IoT Owner privileges are required to browse the registry and manage devices. The downloaded project credentials file contains secure information. Store it in a safe place! Google IoT Core - Cloud IoT Core is a fully managed service that allows you to easily and securely connect, manage, and ingest data from millions of globally dispersed devices. Cloud IoT Core, in combination with other services on Cloud IoT platform, provides a complete solution for collecting, processing, analyzing, and visualizing IoT data in real time to support improved operational efficiency. IBM Watson IoT Platform - Securely connect, collect and start processing IoT data quickly and easily with Watson IoT™ Platform. And because it uses IBM Cloud, your company can scale and adapt quickly to changing business needs without compromising security, privacy or risk levels. There are scenarios where an IoT hub is not required, or rather required for the microServiceBus Node. For instance, if you have already built a working solution and only require Device Management (OTA, logging, monitoring, vulnerability scan and control), -the “No IoT Hub” option might be best suited for you."},{"relativeUrl":"/working-with-external-source-code-providers","url":"http://127.0.0.1:4000/working-with-external-source-code-providers","title":"Working with external source code providers","content":"Although microServiceBus.com come with version control, you might consider using tools you’re already familiar with such as GitHub or Azure DevOps. GitHub and Azure Devops integrations are done on Organization level. It might therefor be more convinient to bind the source code provider to the ROOT Organization as all Scripts and Services will then become available for all other Organizations Tip of the day: Unless you want to keep your Scripts and Services in a separate repo, create a directory in your source control for all mSB files. This action will create GitHub Webhooks which will be available in your GitHub repo under Settings/Webhooks. This action will create Service hooks which will be available in your Project under Service hooks."},{"relativeUrl":"/working-with-schemas","url":"http://127.0.0.1:4000/working-with-schemas","title":"Working with Meter schemas","content":"Meter schemas are the definition of all properties and setting of meters. Meter schems are used when working with Meter Cconfiguration and can be cusomized to your needs. See also Working with meter configuration how the schemas are used on the Node When creating a Meter configuration, you select a schema aligned with your meter, such as Mbus TCP or Modbus RTU. You then proceed to add Datasets, Datapoints and Metadata. When you save your configuration, you have essentially added the configuration to your Node.\nServices running on your Node, such as Modbus master will read the configuration to access the meter/sensor and retrieve the data. The base structure of the schema is always the same. Hence, it needs to be generic. The table below explains some of these terminologies in the context of different types of meters and sensors: This is not the place to explain everything about schemas, but we will cover enough to get started. You should have a common knowledge about JSON before you get started.\nEvery section in the schema will have fields like: The sample above defines a meterinfo element with four properties; id, manufacturer, model and meterType *all of which are required. The JSON output would look something like this: The sampel above decsribes an element called metadata which is of type “array”. The “items” element defines the structure of the containing objects, which in turn can have their own fields as decribed above. Needless to say, -the easiest way to get started is to copy an existing schema and customize it to your need. The root element is always an “object” and defines the unique identifier ($id) which needs to be unique throughout all schemas in the microServiceBus.com instance. The name and description is shown in the drop-box when the user selects the schema. There are five mandatory sections of a schema: There are some meters of similar kind such as MBus TCP, MBus RTU W-Mbus. These are all similar and would also share the same $baseType (“MBUS”). Related to the sample above, this could be “Modbus TCP” for example. The meterinfo section is metadata about the meter and would always look the same:\n| Field | Description |\n| ————– |————-|\n| id | A unique identifier of the meter | \n| meterType | E.g. Energy meter | \n| manufacturer | E.g. Elvaco | \n| model | E.g. CMeX50 | The connectivity section needs to be customized to provide all properties needed to connect to the device The datasets section needs to be customized to provide all properties needed to read the device The datasets section needs to be customized to provide all properties needed filter the telegram The metadata section should not be changed and gives the user the option of adding additional information."},{"relativeUrl":"/import-nodes-using-csv-files","url":"http://127.0.0.1:4000/import-nodes-using-csv-files","title":"Import nodes from CSV files","content":"For users who need to create many Nodes, we recommend using the CSV import rather than creating one at the time from the Node page. Alternately, users can also use the microServiceBus.com© API, which is not going to be covered in this article. To use the import file feature, it’s important that the file follows a specific format which is covered in the next section. Once the file is imported and validated, it is sent of for processing. This step might take a few minutes depending on the number of records in the file. When the process is completed, all users will get notified in the portal and an email is sent to the user who initiated the import.\nWhen your file is ready to be imported, you can import it from the Nodes page by clicking the CREATE NODE drop-down button at the top, and then select the Import from CSV option. The format must align with the following:"},{"relativeUrl":"/meter-configuration","url":"http://127.0.0.1:4000/meter-configuration","title":"Working with meter configuration","content":"Assigning individual configuration to Nodes is an important aspect of IoT as Nodes may be integrating with different meters, sensors and other equipment from one site to another. Even if they are connected to the same kind of equipment, connecting might require specific settings. Node `Meter Configuration’ allows you to create any number of specific settings that can be accessed from the Node and later used to connect, read and update meters. See also Working with Meter schemas for a better understanding of schemas and how you can customize them. As there are many different words describing similar things, there are a few commonly used terms that might be good to familiarize yourself with. Datasets define the meter connected to the Gateway. If you were to connect to an Modbus meter, the meter would be a Dataset. If on the other hand were connecting to a MBus meter, the sensors connected to the Mbus master would represent the Dataset. In cases such as Modbus, you may have any number of Datasets as other meters may be connected to the meter connected to the Gateway. In this case, each Dataset would have a Slave Id and Function. While a Dataset represents the meter or sensor, the Datapoint represents a value of interest. If you for instance, an MBus telegram may have any number of Data blocks, where each Data blocks represents a different reading such as Indoor temperature and Outdoor temperature. Each Data blocks is a Datapoint. Modbus meters have Registers which collectively holds many values. Each of those values is a Datapoint. Meter schemas defines the structure of the Meter Configuration and is tailored to serve a specific protocol. There are several schemas already available in microServiceBus.com, but you are free to create your own. Each schemas is devided into three top level sections: General information about the meter such as identifier, manufacturer and model The Connectivity section holds the necessary information about how we can connect to the meter such as Ip address or serial port See Datasets description above. Meter Configuration is available through the Action menu on the Nodes page or through the CTRL+R option by typing Select a type of meter from the drop list and click the ADD CONFIGURATION button. This will open the configuration dialog where you can set all the parameters. Saving the configuration, automatically updates the state of the Node. You can verify this by going to the properties page of the Node and click DEVICE STATE button. The desired section should have a msbConfig field with a URI pointing to the configuration. The Meter Configuration is available in the Node services using the following command:"},{"relativeUrl":"/migration-information","url":"http://127.0.0.1:4000/migration-information","title":"Migration information","content":"microServiceBus.com has been undergoing a migration which is coming close to general availability. The new release, scheduled for late May 2020, promises improved performance and scale, but also a platform allowing us to adapt new features at a much higher rate.\nEverything will work as normal part from two things: After the release has come available, you will be prompt to change your password. The reason for this is that we cannot read and migrate your password as your password information is not accessible to us. We still offer a free edition of microServiceBus.com, but we are no longer supporting the free IoT Hub. If you have a free IoT hub, you’ll need to migrate it to one from Microsoft, AWS or IBM. This process is simple and will provide you with more features and a more robust solution. Simply create a new IoT Hub, copy the connection information such as connection string or Access token depending on your choice of provider. Navigate to the Organization tab and click the SWITCH IOT PROVIDER button. Select you provider and click the CHANGE IOT PROVIDER button. All your existing Nodes will instantly be migrated to your new IoT Hub. First time using an IoT Hub? Check out the links below for more information:"},{"relativeUrl":"/node-installation-scripts","url":"http://127.0.0.1:4000/node-installation-scripts","title":"Node installation scripts","content":"Node installation scripts can optionally be used to install the microservicebus-node agent on a device. There are two versions of the scripts targeting Linux and Windows based devices. Running the scripts will install node.js if needed and proceed with downloading and installing the microservicebus-node agent. The scripts require a set of parameters which are generated at runtime, and are therefor not particularly useful to use outside the scope of creating a device. The content of the scripts can be downloaded here: Installation script for Linux Installation script for Windows"},{"relativeUrl":"/node-vpn-interfaces","url":"http://127.0.0.1:4000/node-vpn-interfaces","title":"Work with Node VPN interface and peers","content":"The microservicebus-node agent can be enabled to host or join a VPN network using WireGuard®. WireGuard® is a modern VPN that utilizes state-of-the-art cryptography. For more information about its supported protocols and cryptography. There are two main purposes for the Node VPN feature: There are scenarios where data is not transmitted to an IoT Hub endpoint, but to other locations using a none TLS or secure protocols. This can be the case when transmitting data to a local SCADA system using for instance IEC 60870-5-104. In such situations you can set up a secure tunnel for transport encryption. When Nodes are operating in a secure environment with no in- or outbound access to internet, a secondary Node can access as a “proxy” from a less secure zone. Before you begin, -WireGuard® needs to be installed on your gateway. You can follow the installation descriptions here to manually install it, or select one of our many Yocto images that comes with WireGuard® pre-installed. The private key is stored securely in Azure Key Vault, and once the key is generated it will only be accessible from the *Node after successful sign in.* Use the Post Up and Post Down fields if you for instance would like the host Node to forward traffic. For instance: The following example adds forwarding when VPN is started *The following example removes forwarding when VPN is shutdown * Please be careful when using forwarding! By default, the IPv4 policy in linux kernels disables support for IP forwarding. This prevents machines that run linux server from functioning as dedicated edge routers. To enable IP forwarding, use the following command: This configuration change is only valid for the current session; it does not persist beyond a reboot or network service restart. To permanently set IP forwarding, edit the /etc/sysctl.conf file as follows: Locate the following line: Edit it to read as follows: Use the following command to enable the change to the sysctl.conf file: If setting up a relay on a machine with multiple IP addresses (such as for a cloud-based VM), you need to specify which IP to use in the settings.json. You can do this by adding the following line on the top level of the file: If your Nodes are online, they should now fetch their respective VPN configurations and establish the connections. Their might be scenarios where you need to connect to the network using for instance your laptop. To do this begin by installing the WireGuard® VPN software from here. It is important to save this file in secure location as as it holds the private key Private keys are not stored in microServiceBus.com for User peers, so it’s important not too loose the file. But if you do loose it, remove the User peer and create a new one. To enable WireGguard logging: If a key get compromised you can re-generate the key by simply clicking the Generate button in the VPN tab. This will give the Node a new private key and update the public key of all Nodes on the network."},{"relativeUrl":"/reviewing-the-auditlog","url":"http://127.0.0.1:4000/reviewing-the-auditlog","title":"Reviewing the Audit log","content":"Audit logs can be used to find out who did what and when. All changes made to entities below are subject for auditing: The Audit logs are available by navigating to the Management page, and selecting the Audit logs tab. Or from individual entities by clicking the AUDIT LOGS button."},{"relativeUrl":"/roles-privilages-and-auditing","url":"http://127.0.0.1:4000/roles-privilages-and-auditing","title":"Roles, privilages and auditing","content":"Users can become members of an Organization by either creating the Organization or by being invited to the Organization by an owner. \nUser security and privileges are managed through Roles. Significant actions such as changing Organization settings or deleting a Node are subjects of Audit logging. microServiceBus.com comes with two roles; Owner and Co-administrator. As a rule of thumb, a Co-administrator can do everything except managing users and the Organization. Co-administrator are also prevented from Claiming Nodes, grant themself access to Nodes and use the remote terminal, although these privileges can be changed by an Owner. More informaiton about how to access Audit logs"},{"relativeUrl":"/run-background-services","url":"http://127.0.0.1:4000/run-background-services","title":"Run background services","content":"Background service is similar to an normal JavaScript or Python Services, but runs in the background independent of Flows and other services. A background service cannot interact with other services or transmit messages to the IoT Hub, but it lets you run background tasks such as checking disk space and other hardware related issues. You can set the Background service either through Node Templates or on the Node Property page. The script below checks that the disk space is not utilized to more than 75%."},{"relativeUrl":"/services-and-scripts-in-microservicebus-in-depth","url":"http://127.0.0.1:4000/services-and-scripts-in-microservicebus-in-depth","title":"Services and Scripts in microServiceBus.com in depth","content":"This page is dedicated to those with a bit of prior knowledge regarding how flows and services in microServiceBus.com works. If you are not familiar with these concepts yet, please visit the Getting started first. When you as a developer is writing a service to use in a flow, you are extending the microservice object microServiceBus.com is exposing. This object has a number of functions and properties that could help you develop your code. First we will go through what is required in your own service, then what is available to you and lastly som best practices. Start() This function will be called when your node starts and your service has been downloaded. @parameters : none @returns : void @example Tip!\nHere it is great to add all your NPM packages. Stop() This function will be called when you disable or restart your node. @parameters : none @returns : void @example Tip!\nHere it is recommended to stop your timers or clear your processes. Process() This function will be called when you send messages from another service to this @parameters : message , context @returns : void @example Tip!\nHere is where you can integrate your services to share data with each other. Tip!\nThese are just some examples of properties you can access. Check the source code at GitHub to find more. Search for new MicroService ;) this.GetCurrentState() Returns the “device twin” or “shadow” of the device from the connected IoT Hub. @parameters : none @returns : Object @example this.AddNpmPackage(npmPackages, logOutput, callback) Downloads the packages in run time and calls the callback when download and installation is completed @parameters : npmPackages (string), logOutput (Boolean), callback (function) @returns : Void @example this.SubmitMessage(msg, format, headers) Creates a new context and sends the message to the next service in the flow in a specified format with or without headers. @parameters : msg (object or binary), format (string), headers (needs to be formatted as following : [{Variable : “[key]”, Value : “[value]”}]) @returns : Void @example this.SubmitResponseMessage(msg, context, contentType) Similar to SubmitMessage but is using the same context. Most often used for Internal- and Outboud services @parameters : msg (object or binary), context (including itinerary and variables), contentType (E.g. ‘application/json’) @returns : Void @example this.Configuration() Used to retrieve Meter Configuration. See Working with meter configuration @parameters : None @returns : All Meter configuration for the Node @example this.GetLocalTime() Used to get local time depending on location set on the Node (Properties page of Node)\n@parameters : None @returns : DateTime @example this.GetInstanceOf(serviceName, callback) Returns the service instance by name. This can be usefull when you have a service that needs to run as a singleton and server multiple services. For instance, if you connect to two or more RTU meters using the same serial port you might have to run the in sequense. In such case you might want to use an Modbus Master service as a singleton to access the actual meter while multiple other services are doing the request. @parameters : serviceName (name of service), callback (err, instance)) @returns : DateTime @example this.SetCronInterval(callback, cronExp) Returns a CRON job which will trigger on interval. @parameters : callback (function that will trigger), cronExp (CRON Expression)) @returns : CRON job @example this.SetCronInterval(cronJob) Stops the CRON interval. @parameters : cronJob (instance of CRON job)) @returns : void @example"},{"relativeUrl":"/site-verification","url":"http://127.0.0.1:4000/site-verification","title":"Site verification","content":"Arguably, one of the biggest challenges when rolling out new solutions, is the on-site installation and setup. Mounting a gateway and getting it connected to the cloud is often a minor part of the complete installation. Lots of wires, meters and other equipment might be required, and it’s vital that everything is connected before the on-site engineer leaves the premises and call it a day. The solution to this is to create a Site Verification test, and let the on-site engineer run the test(s) to verify it’s all up and running. Site verification test is nothing but a normal unit test. If you have ever written a unit test before, this should be really easy. If not, don’t panic. The Test-Driven Development pattern is very easy to understand. The Site Verification Test is using mocha which comes preinstalled for you Node. Writing a verification tests are just like writing a normal Service. In the microServiceBus.com portal navigate to Scripts & Services using the navigation menu. Click the CREATE NEW button. Set a name, filename and description. Before you hit the CREATE button, select Test file in the Service type drop-down list. In many scenarios you need the site engineer to be able to provide input to the test, such as which serial port or IP address to use. As with normal Services, add your parameters in the Static Properties tab. Make sure to use well descriptive names as these properties are going to be presented in the Site Verification Application Inside your test script, you can access these properties using the following syntax: Every test case file follows the same basic pattern. First, you have a describe block: describe is used to group individual tests. The first parameter should indicate what we’re testing — in this case, we’re going to make sure we’re connected to a meter, as we’ve passed in the string ‘Meter connection’. Secondly, inside the describe, we’ll have it blocks: it is used to create the actual tests. The first parameter to it should provide a human-readable description of the test. For example, we can read the above as “should be a valid IP address”, which is a good description of what we expect. The code to implement the test is then written inside the function passed to it. All Mocha tests are built from these same building blocks, and they follow this same basic pattern. To validate the IP Address, we can use a Regular expression, and test it with the IP Address parameter provided by the site engineer: Your test can have any number if if blocks! Before you can run the test on the Node you need to set the Node in “Test mode”. Navigate to the Node page and select properties from the Action menu. On the Node properties page, set the Mode to “Test mode”. Also click the Identities tab on the top and copy the serial number (set it if empty). Last, save the changes. On the Save confirmation dialog, click the “VIEW QR CODE” button. User your phone to navigate to the site verification app. Follow the instructions on the screen to verify the installation."},{"relativeUrl":"/using-node-terminal","url":"http://127.0.0.1:4000/using-node-terminal","title":"Using the Node terminal","content":"The Node terminal gives users a remote ssh session to the Node. This can be very helpful in times where you need full control of the gateway. The Node terminal is only available to Organization Owners, and can be accessed either through the ACTION menu on the Node page or by hitting CTRL+R and type: As you open the terminal, you are logged in as the same user as the microservicebus-node service is running with. Depending on your setup, this might only give you limited privileges. Also, the back-end of the terminal is hosted by microservicebus-node process. If you kill this process, -you terminate the terminal session."},{"relativeUrl":"/using-the-editor","url":"http://127.0.0.1:4000/using-the-editor","title":"Default keyboard shortcuts","content":"microServiceBus.com uses a Script/Service editor that provides the features and performance of today’s native editors, such as syntax highlighting for over a hundred languages, selecting from several themes, code folding, an API, and much more. Refer to this section for tips to improve your experience using the Script/Service editor."},{"relativeUrl":"/working-with-service-properties","url":"http://127.0.0.1:4000/working-with-service-properties","title":"Working with service properties","content":"The service property window is where you define the characteristics of your service. All properties are divided into three categories; General, Static and Security properties. While Static and Security properties are specific to each micro service, the General properties are generic and applies to all services. Most properties can be set using dynamic expressions. For instance, the sample below shows Static properties for the File outbound service. While the Path property is staticly set, the File name property is set to %guid%. This is called a Marco, and is unique to certain services. For the File outbound service, this means the name is going to get a unique name. Sometimes you might want to use some value from the payload to set a property. In such cases we use brackets. In the sample above we are transmitting an order with a property called orderid. You can combine two or more properties such as [firstName]_[lastName].json. You can also use context variables, in which case use curly brackets as above."},{"relativeUrl":"/what-is-a-node","url":"http://127.0.0.1:4000/what-is-a-node","title":"What is a Node?","content":"With an understanding of what a Micro Service is, it’s time to look at the Node. The Node is the agent running on your gateway or device. It is connected, owned and managed by an Organization. The Node is responsible for starting and stopping Flows and Services. -Essentially, the Node is where everything get processed. Every Service has a property called “Node”, which tells you where the Service is going to be executed, which could be any or all Nodes, regardless of location or platform. For instance, in the sample below we have a Flow, which describes the interchanges of the message. In this sample we have three Services; an Inbound FILE Service, a JavaScript Service and a Outbound Azure Send Event Service. These Services can all run on the same or on different Nodes. In the sample above, all Services are run on the same Node. When a file is save in a specific folder, the Inbound FILE Service will pick it up, create a Messages and pass it back to the Node orchestrator. The Node will attach the Flow definition to the Message and check to see if the next Service in line (the JavaScript Service in this case) is hosted on the same Node. If this is the case, as in our sample, the Service will just pass the Message to the next Service without ever leaving the Node. If Services are configured to be executed on different Nodes, the Node will send the Message to microServicebus.com, which in turn will re-direct the Message from the first Node to the Node hosting the next Service in line. To send a Message from one Node to the other as in the sample above, you’d need to enable the “Allow send” on properties window of the first Node. You access the Nodes properties through the Action button on each Node on the Nodes page, and there are many properties that might be important: Disconnect policies are very important, and dictates when a device is considered off-line and what action to take. Clicking the ENVIRONMENT button will present you with valuable information such as Networks, CPU, Memory and environment variables. Most IoT platforms respects the notion of State. Microsoft calls it Device Twin, whereas Amazon calls it Things Shadow. In both cases it is a JSON document that represents the State of the Node. Click the DEVICE STATE button to review and change the State. See the Reviewing the Audit log section. By clicking the RETRIEVE SYSLOG button a call is sent to the Node to compress and submit syslogs to the portal. These logs can be downloaded from the Logs tab. Nodes are running on the Node.js platform, and as such is supported on every platform node.js is working on, which luckily is most of them. For more information about Node.js, please visit nodejs.org"},{"relativeUrl":"/what-is-a-micro-Service","url":"http://127.0.0.1:4000/what-is-a-micro-Service","title":"What is a micro Service?","content":"A micro service is a part of a larger more complex solution, with a specific role. The service may be of different types where the most common types are: In microServiceBus a micro service is used in one or several flows. microServiceBus.com provides a large set of services out of the box, that you may use freely in your flows. Navigate to the main menu and select Scripts & Services. Click the button Create New and select In this example you're going to start from scratch with 'Create New'. Next, we’ll need to give the service a name, a description and select what kind of service. and press Create… In the new window (Edit Service Script) you can now: For now we’ll simply press Edit (top right) and edit our service template. We will only make a small modification to the template service and provide an additional JSON key/value “hello:World” and lower the trigger interval to every 5 second. Update the upper part of the service to match: Since we’re doing a minor change to the flow we’ll choose Update minor in drop-down to the botton right. Now, press Save and let’s celebrate your first custom service! :-) You now have the ‘MyGoodOldTimer’ service avaliable in the Toolbox, when modeling your flow (see below)! Continue on to how flows work to realise logic Introduction to flows Documentation in more depth on writing scripts can be found at Microservices in depth"},{"relativeUrl":"/what-is-a-flow","url":"http://127.0.0.1:4000/what-is-a-flow","title":"What is a Flow?","content":"Flows are entities responsible for orchestrating the execution of Services. Each instance of a flow, sometimes referred to as a Itinerary, holds state of all Services, Variables and Messages. While Variables and Messages may change over the lifetime of the Flow, the structure remains immutable, meaning once started, -Services and their related connections will not change although updated in the portal. You create Flows by going to the Flow page using the menu or by using the short-key CTRL+R and type “flow”. Clicking the “Create new” button on the top of the page takes you to the a page where give your flow a name and description. Clicking the “Create” button takes you to the Flow details page, and will present you with the Flow designer: The Flow designer is made up of two parts; the toolbox and the designer. The toolbox shows all the Services created in your organization and Services that belongs to the Root organization which is not directly accessible to you, other than you have access to all its Services. As you might remember from the What is a Service? section, there are different kind of Services. Only three kind of Services are visible in the toolbox. Inbound Services starts the Flow. These Services will always create the Message along with the context. Inbound Services are often triggered on an interval or event such as reading a Modbus register every minute. Outbound Services receives Messages from Inbound- or Internal Services and are used to control meters and devices or transmitting Messages to IoT Hubs for example. Internal Services are generally used to manipulate Messages or Variables, such as transforming, batching or compressing Messages. Each instance of a flow (itinerary) has ONE Message which might change over the course of the lifetime of the itinerary. Messages are often a JavaScript object but does not have to. Connecting two Services instructs the orchestrator to pass the execution from one Service to the other. The default routing condition is ‘true’, meaning the Message will always take this route. However, you can set the routing condition by double-clicking the connection and set the route variable. Eg. Setting this condition means only route Messages to the destination if the temperature is more than 30 degrees. Variables are available through the the whole execution of the itinerary and can be read or updated. However, you need to create them prior to using them. Click the “VARIABLES” button at the bottom to add variables."},{"relativeUrl":"/what-is-a-flow#variables","url":"http://127.0.0.1:4000/what-is-a-flow#variables","title":"What is a Flow?","content":"Flows are entities responsible for orchestrating the execution of Services. Each instance of a flow, sometimes referred to as a Itinerary, holds state of all Services, Variables and Messages. While Variables and Messages may change over the lifetime of the Flow, the structure remains immutable, meaning once started, -Services and their related connections will not change although updated in the portal. You create Flows by going to the Flow page using the menu or by using the short-key CTRL+R and type “flow”. Clicking the “Create new” button on the top of the page takes you to the a page where give your flow a name and description. Clicking the “Create” button takes you to the Flow details page, and will present you with the Flow designer: The Flow designer is made up of two parts; the toolbox and the designer. The toolbox shows all the Services created in your organization and Services that belongs to the Root organization which is not directly accessible to you, other than you have access to all its Services. As you might remember from the What is a Service? section, there are different kind of Services. Only three kind of Services are visible in the toolbox. Inbound Services starts the Flow. These Services will always create the Message along with the context. Inbound Services are often triggered on an interval or event such as reading a Modbus register every minute. Outbound Services receives Messages from Inbound- or Internal Services and are used to control meters and devices or transmitting Messages to IoT Hubs for example. Internal Services are generally used to manipulate Messages or Variables, such as transforming, batching or compressing Messages. Each instance of a flow (itinerary) has ONE Message which might change over the course of the lifetime of the itinerary. Messages are often a JavaScript object but does not have to. Connecting two Services instructs the orchestrator to pass the execution from one Service to the other. The default routing condition is ‘true’, meaning the Message will always take this route. However, you can set the routing condition by double-clicking the connection and set the route variable. Eg. Setting this condition means only route Messages to the destination if the temperature is more than 30 degrees. Variables are available through the the whole execution of the itinerary and can be read or updated. However, you need to create them prior to using them. Click the “VARIABLES” button at the bottom to add variables."},{"relativeUrl":"/what-is-a-flow#message","url":"http://127.0.0.1:4000/what-is-a-flow#message","title":"What is a Flow?","content":"Flows are entities responsible for orchestrating the execution of Services. Each instance of a flow, sometimes referred to as a Itinerary, holds state of all Services, Variables and Messages. While Variables and Messages may change over the lifetime of the Flow, the structure remains immutable, meaning once started, -Services and their related connections will not change although updated in the portal. You create Flows by going to the Flow page using the menu or by using the short-key CTRL+R and type “flow”. Clicking the “Create new” button on the top of the page takes you to the a page where give your flow a name and description. Clicking the “Create” button takes you to the Flow details page, and will present you with the Flow designer: The Flow designer is made up of two parts; the toolbox and the designer. The toolbox shows all the Services created in your organization and Services that belongs to the Root organization which is not directly accessible to you, other than you have access to all its Services. As you might remember from the What is a Service? section, there are different kind of Services. Only three kind of Services are visible in the toolbox. Inbound Services starts the Flow. These Services will always create the Message along with the context. Inbound Services are often triggered on an interval or event such as reading a Modbus register every minute. Outbound Services receives Messages from Inbound- or Internal Services and are used to control meters and devices or transmitting Messages to IoT Hubs for example. Internal Services are generally used to manipulate Messages or Variables, such as transforming, batching or compressing Messages. Each instance of a flow (itinerary) has ONE Message which might change over the course of the lifetime of the itinerary. Messages are often a JavaScript object but does not have to. Connecting two Services instructs the orchestrator to pass the execution from one Service to the other. The default routing condition is ‘true’, meaning the Message will always take this route. However, you can set the routing condition by double-clicking the connection and set the route variable. Eg. Setting this condition means only route Messages to the destination if the temperature is more than 30 degrees. Variables are available through the the whole execution of the itinerary and can be read or updated. However, you need to create them prior to using them. Click the “VARIABLES” button at the bottom to add variables."},{"relativeUrl":"/what-is-a-micro-service","url":"http://127.0.0.1:4000/what-is-a-micro-service","title":"What is a micro Service?","content":"A micro service is a part of a larger more complex solution, with a specific role. The service may be of different types where the most common types are: In microServiceBus a micro service is used in one or several flows. microServiceBus.com provides a large set of services out of the box, that you may use freely in your flows. Navigate to the main menu and select Scripts & Services. Click the button Create New and select In this example you're going to start from scratch with 'Create New'. Next, we’ll need to give the service a name, a description and select what kind of service. and press Create… In the new window (Edit Service Script) you can now: For now we’ll simply press Edit (top right) and edit our service template. We will only make a small modification to the template service and provide an additional JSON key/value “hello:World” and lower the trigger interval to every 5 second. Update the upper part of the service to match: Since we’re doing a minor change to the flow we’ll choose Update minor in drop-down to the botton right. Now, press Save and let’s celebrate your first custom service! :-) You now have the ‘MyGoodOldTimer’ service avaliable in the Toolbox, when modeling your flow (see below)! Continue on to how flows work to realise logic Introduction to flows Documentation in more depth on writing scripts can be found at Microservices in depth"},{"relativeUrl":"/getting-started","url":"http://127.0.0.1:4000/getting-started","title":null,"content":""},{"relativeUrl":"/what-is-an-organization","url":"http://127.0.0.1:4000/what-is-an-organization","title":"What is an Organization?","content":"Organizations separates ownership of artefacts (see Flows, Services and Nodes). This is also where you manage users and integration with ServiceNow, Cisco Jasper, Azure DevOps, GitHub and more. There are two roles within your organization; Owners and Co-Admins. Only owners can do user administration and moving nodes between organizations. To add a user to your organization, go to the Organization page and click the “ADD CO-ADMIN” button. Provide the email address of the person you’d like to invite. The invited person will then get an email with instructions of how to register and join the organization. If the invited person already have an account, he or she can go the the Organization page of any organization to accept the invite. ADFS is a standards-based service that allows the secure sharing of identity information between trusted business partners (known as a federation) across domains. The ADFS integration allows for people in your organization to authenticate themselves using your organization’s ADFS. By setting up integration with ADFS you’re essentially telling microServiceBus.com to trust your domain. Should you prefer having users signing in with an Active Directory account, you can provide necessary settings on the Organization page. For more information:"},{"relativeUrl":"/microservicebus-release-management","url":"http://127.0.0.1:4000/microservicebus-release-management","title":"microServiceBus.com release management","content":"microServiceBus.com (portal) along with agent packages; microServiceBus-node and microServiceBus-core are normally release as: New releases of the public portal (https://microServiceBus.com) are initially released to the developing environment (DEV) dev.microServiceBus.com, which is publicly available with no connection to the production data. This environment is predominantly used for developing and integration testing. Once testing is complete, changes are replicated to the STAGE environment (stage.microServiceBus.com). This environment is connected to the same data source as the production environment and should be used for acceptance testing. When code is submitted to the STAGE branch, ALL stage environments are affected including private and self-hosted, environments. Once acceptance testing is complete, PROD and STAGE environment are “swapped”, meaning IP addresses of https://microServiceBus.com and https://stage.microServiceBus.com are swapped leaving the STAGE environment in “last working state” and can be used as backup should issues be found in a later state. The process of swapping PROD and STAGE for private and self-hosted environments are done upon acceptance of the customer. It is however recommended to update at least once a month. Depending on the underlying architecture of the hardware, updates of the mSB-node can be handled differently. If, for instance, the mSB-node package is running in a Ubuntu Snap or a Docker container the updates of these packages are handled either manually or automatically along with the selected infrastructure. Should a customer want to have control over the releases of mSB-node, they can choose to fork the microServiceBus-node github repo and/or publish their forked repo as a custom npm package. Following this pattern, customer can choose when they decide when to publish new releases. Worth pointing out, that although this options gives the most control, it also requires a great deal of insight. Organizations can also control the version of microServiceBus-core using the settings on the Organization. The Node Version setting can be set to either latest, beta, ignore or a specific version. Normally, organizations would choose latest or a specific version for their production environment, however if you’d like to test the beta version on one or a subset of nodes, you can tag the node with BETA on the property page of the node. Once your Flow are in production we recommend locking the version of each Service by opening the property window of each Service and check the “Lock to version” checkbox. This will make sure the specific version of the Service is used, regardless of if it has been updated. Sometimes we need to test an update of a Service in production, while making sure other Nodes are still using the last stable version. This is common in scenarios where a Flow is used by many Nodes using tags. In such cases, a specific tag is applied to one or more nodes, such as “Amsterdam”, and rather than configuring a Service run on a specific Node, you’d use the tag instead (#Amsterdam). However, using tags this way will force all Nodes using the same version of the Service. -If you want to run one of the nodes on the latest version, you can apply the “BETA” tag to the node, in which case it will always ignore the “Lock to version” setting"},{"relativeUrl":"/controlling-nodes","url":"http://127.0.0.1:4000/controlling-nodes","title":"Controlling Nodes","content":"There are two recommended ways of restarting nodes. Navigate to the Nodes page, find the ACTION button for your Node then click restart Restarting a node by command Hit CTRL + R , and type restart [YOUR NODE] Example: restart node-00001 Will make the node to do a complete reboot of the system Will completely turn the system off and you will not be able to access the node unless you do a power cycle. Wiping the node will clear its settings! Moving a node to another organization will cause the Node to reconfigure, restart and join a new organiztion based on it’s IMEI identifier Sometimes it can be very useful to look back in time to find patterns of communication issues and other events. For this we have History data Historic data is not sent to microServiceBus.com, unless requested. The Audit log shows any action taken on Nodes Environment data refers to things like available memory and storage along with environment variables and CPU information."},{"relativeUrl":"/get-remote-access-to-your-nodes","url":"http://127.0.0.1:4000/get-remote-access-to-your-nodes","title":"Get remote access to your Nodes","content":"There are times when you might need to access your Nodes to dig through the local file system, check log files locally or just do some configuration of networks and services. SSH passwords is sufficient when you have a few Nodes, but imagine the hassle and the ensuing fight you will have with security when all of these passwords are stored on a file on your local computer. Or when you send a password to your collegue. Enter, SSH keys. By uploading the public part of your own SSH key to microServiceBus.com, you can get remote access to your Nodes. You will get your own user on the machine and therefore traceability on actions taken during your SSH sessions. Note!\nYou will need to have the snap microServiceBus-DAM installed to be able to add SSH keys to the device microServiceBus-dam is the device access manager that handles all the users, keys and secure transfers of these. To be able to get remote access to your device you will need to install the snap and link it to the microServiceBus-node snap. microServiceBus-dam is currently only available in a Ubuntu core environment. Install the snap with the following command: Navigate to your user page Manage user. Go to the tab SSH keys and either type in a username or have us generate one for you. These are case insensitive and will always have all lower-case characters. This will be the user that you use for your SSH session towards the Node. Refresh the page and navigate to the same tab. You can now add a SSH key that is linked to your user. If you do not have a SSH key you can create one by starting up a terminal on your computer and run: Add your device name and the public part of your key. You are now ready to request remote access to Nodes to be able to log in directly on the device. Navigate to the node page Nodes. Click on the Actions dropdown on the Node you would like to get access to and press on Grant Access. The Node will now fetch your public key and add it as a user on the device. The key will be removed after 3 hours for security reasons, so if you need more time than that you will have to Grant Access again. Once you have your public key uploaded and have Granted Access for yourself, you can now start a SSH sesssion from your device to the Node with the command: You can now do all of your operation, configuration and routing without having to worry about security and passwords ever again."},{"relativeUrl":"/groups-and-tags","url":"http://127.0.0.1:4000/groups-and-tags","title":"Grouping and tagging Nodes","content":"Tags are commonly used when you want to address an action on many Nodes such as when patching Nodes through the API, or as group when developing Flows that should run on multiple Nodes. Tags can be set on both Nodes and Flows. There are a few tags that are built-in such as #ALL and #BETA, but generally you’d create your own tags. For example, lets assume you create a flow that should read and transmit the current state of a heat pump. Lets also assume you’d be reading the values from the heat pump using Modbus. If every Node in your Organization is connected to a heat pump and you want the same Flow to execute an all Nodes, you would set the Node attribute of the first (inbound) Service to #ALL: The #ALL tags, as the name implies, causes the this Flow to run on all Nodes An other scenario would be where not all Nodes are connected to heat pumps, and you only want the flow to execute on a sub-set up Nodes within the Organization. It could also be that some of your Nodes are using a different manufacture of heat pumps, which in turn might require a different Flow/Service. In such cases, you’d be better off using a custom tag such as #NIBE-F2120: You can patch individual Nodes from the the Node page in the portal, but when you want to patch many Nodes, this approach is not efficient. In such cases you are better off using the API. For instance if you want to update the firmware on many Nodes you should use the Update Firmware API (/api/organizations/{id}/tags/{tag}/updatefirmware), where {id} is the Id of your Organization and the {tag} is the used to filter the Nodes. Again, if you want to update all the Nodes use the #ALL tag: While if you are a bit more cautious, you might consider rolling the update per region: The last sample assumes you have a number of Nodes with “BERLIN” tag set. Tags can be applied to Nodes from the Node Property page: You might also consider using the API: The majority of the Node is defined in a package called microservicebus-core, and you can set the preferred version at the Organization page. However, sometimes you might want to test one or two Nodes with the BETA release before updating all Nodes. To do this, you can tag the Node with #BETA or #EXPERIMENTAL. After restarting the Node the microservicebus-core component will update to BETA or EXPERIMENTAL release."},{"relativeUrl":"/managing-firmware-and-device","url":"http://127.0.0.1:4000/managing-firmware-and-device","title":"Managing firmware and devices","content":"The ability to update firmware’s or application containers is essential to secure your system. Device information refers to low-level components of your hardware, such as kernel, firmware, containers and other settings such as memory, storage and environment variables. All these can be accessed through a single view in on the Nodes page. From the Nodes page, click the ACTION button of any one of your online Nodes and select *Device. This will send a request to your Node and open the Device information dialog. The dialog presents four different tabs: This tab reveals common resources such as CPU, Memory and network, all to get a good overview of resource usage, but also a good place to find the IP address of your Node. Yocto based devises, usually comes with two or more kernel partitions. These are manage by a bootloader manager such as RAUC. The Device information dialog provides detailed information about each partition such as which is active, when it was activated and more. The Device information dialog also gives you the options of settings which partitions should be booted. You can also update the firmware from this dialog (also available using the microServiceBus API). If you are running Ubuntu Core or Ubuntu IoT, this is your go-to place for managing Snaps running on your device. The list gives you an overview of all installed Snaps and lets you refresh (update) them by clicking the REFRESH button. Keep in mind that updating Snaps may require rebooting the system. Although you can update your Snaps using this dialog, you may consider using the microServiceBus API to update more or all devices at once. Environment variables are a variables whose value is set outside the program, typically through functionality built into the operating system or microservice. An environment variable is made up of a name/value pair, and any number may be created and available for reference at a point in time. Configuring your system using bash scripts is a powerful and easy way to make sure consistency and integrity of your system is kept. Bash scripts are created just as you create a microservice, but make sure to Service type of your script to Patch script, as it will otherwise not be visible in the Device information dialog. With the Patch script created, you can select it in the drop-down list, and click the EXECUTE button to have the script executed on the gateway."},{"relativeUrl":"/provitioning-of-nodes","url":"http://127.0.0.1:4000/provitioning-of-nodes","title":"On-boarding and provisioning of new devices","content":"There are three supported ways you can provision devices: Once you have installed a Node and are ready to start it up, you can do so using a temporarily verification code which you can get from the Nodes page. The code is valid for 30 minutes and can be used as follows: The code and the Node name are only required the first time you start the node Node. Once provisioned, you can start it using only: For more information about how to install a Node Anonymous signin means the Node registers it self to be claimed in the microServiceBus.com portal. This action require either a Site manager role in multitennant environments such as microServiceBus.com, or Owner of an Organization in a Private- or Self hosted environment. Start the Node using only start: When claiming the node, it will be given whatever name you choose. By default it will be part of your current Organization, but you may change to any other Organization you are Owner of. IMPORTANT! Provisioning a Node using anonymous signin will send device information such as IP and MAC addresses to the microServiceBus.com portal (for identifying which Node to claim). If the MAC address is whitelisted (see Using MAC whitelist section below) the MAC whitelist option will surpass the Claim option and the Node will get automaticly provisioned (provided it has not been used before). The media access control address (MAC address) of a device is a unique identifier assigned to a network interface controller (NIC). Each device has it’s own unique MAC address, and you can register these addresses in microServiceBus.com to simplify the on-boarding of devices in bulk. Once a device has been provisioned using the MAC address, the address is consumed and can not be used again. It’s recommended only to register devices that you are planning to provision at a specific point in time. Keep in mind that MAC addresses can be spoofed. Follow the steps below to on-board devices using MAC addresses The International Mobile Equipment Identity or IMEI is a unique number to identify the modem of the device. Before provisioning devices using the SIM card id, you need to integrate your organization with Cisco Jasper. To setup the Cisco Jasper integration, follow this guide. Once integrated, you can start the Node using only the –imei:"},{"relativeUrl":"/user-management","url":"http://127.0.0.1:4000/user-management","title":"User management","content":"Sharing is caring, and that goes for your organizations as well. Time to go through different user scenarios for your organizations. There are two roles within your organization; Owners and Co-Admins. Only owners are authorized to do user administration and moving nodes between organizations. To add a user to your organization, go to the Organization page and click the “ADD CO-ADMIN” button. Provide the email address of the person you’d like to invite. The invited person will then get an email with instructions of how to register and join the organization. If the invited person already has an account, he or she can go the Organization page of any organization to accept the invite. Note in the picture above that once you have added a Co-Admin to your organization you now have the option to assign the Owner role to that user. You need to be owner of an organization to assign the owner role. Once you have assigned the owner role to a user it can’t be reverted by you, only the user in question can remove the role assigned to them. ADFS is a standards-based service that allows the secure sharing of identity information between trusted business partners (known as a federation) across domains. The ADFS integration allows people in your organization to authenticate themselves using your organization’s ADFS. By setting up integration with ADFS you’re essentially telling microServiceBus.com to trust your domain. Should you prefer having users sign in with an Active Directory account, you can provide necessary settings on the Organization page. Once you have clicked the Edit button on the Organization page you will have to edit these fields: Once the correct information is applied, you should be able to login with your Active Directory account. Don’t forget to invite your Active Directory account before you try to login with it."},{"relativeUrl":"/working-with-alerts","url":"http://127.0.0.1:4000/working-with-alerts","title":"Working with Alerts","content":"Managing and taking actions on Alerts is a crucial part of IoT Device Management and allows you to react to events such as notifying a technician to replace a sensor if the battery is low or send a text message if the pressure of the heat pump is running high. There are several built-in Alerts and you can also configure your own. Alerts are only available on managed Organizations and can be enabled on the Organization page. An Alert can be created from anywhere but most commonly from a Node and is commonly some abnormality you’d like to take action on. All incidents have an identifier (error code), a description and an action. Actions are described in detail below. A Custom Alert is implemented using three parts: The identifier (error code), description and an action. Navigate to the Organization page, and scroll down to the ServiceNow section. If your organization is managed, the MANAGE ALERTS button is enabled. Click the button to open the Manage Alert dialog. By default, there should be two policies already created for you; Unhanded Exceptions and Offline Nodes. These are described in detail in the Default policies section below.\nClick the Add new record button on top to create a new row in the table. Set a Error code and describe the Alert. Finally, select an Action and set the parameters. \nPlease note that you can have multiple actions on the same Error code. The * Send issue email* action sends an hourly aggregated notification of all incidents to participants you’ve configured clicking the Params button (…). The to element can hold a comma separated list of email addresses who subscribes to this event. Similar to the * Send issue email* action, this action sends an hourly notification to participants you’ve configured clicking the Params button (…). Sample The Call API will send a POST request of every incident to a REST service of your choice. Configure the parameters as the table below: Using bearer token Using custom header The Create ticket action will create an Alert in ServiceNow and does not require any parameters. This action is part for the Unhanded Exception (error code 90000) default policy. When Nodes come offline a workflow will be triggered which does the following:"},{"relativeUrl":"/gettingStarted-list","url":"http://127.0.0.1:4000/gettingStarted-list","title":null,"content":""},{"relativeUrl":"/quickreference-list","url":"http://127.0.0.1:4000/quickreference-list","title":null,"content":""},{"relativeUrl":"/news","url":"http://127.0.0.1:4000/news","title":"News","content":"Although there has been several small fixes in this release, this update is to align microServiceBus.com with underlying platforms and dependancies. IMPORTANT! Due to changes in .Net 8, API keys needs to be regenerated. Our support team will contact you and assist you if needed. microServiceBus.com will be undergoing a migration to .net 8 in November, whilst this update primarly focus on simplyfying the deployment in November/December. This includes refactoring of configuration settings, security updates and bringing all dependancies to latest version. Changes in microservicebus-core mentioned below has been available for testing since May 2022. All Nodes using “latest” will automaticly be updated once restarted. If you have not yet tested the BETA version and don’t want this update at this moment, navigate to the Organization page, click EDIT on the NPM feature and set the “Default version” to 3.16.1. THIS CHANGE WILL BE APPLIED 31 st of Aug (tomorrow) As summer and vacations are coming to Sweden we’re planning on doing some re-factoring and aligning our products with the latest platforms and frameworks. microServiceBus.com (portal) will be migrated to .net6, microservicebus-node to Node.js 16+ and our Yocto images to Kirkstone. We expect all of this to be ready by Jul-Aug and we will freaze the backlog until then. The new Python based Node is intended for smaller devices or where Node.js is not working. It comes with some limitation in comparison to mSB-node (Node.js), but is still a very manageable alternative. Enable / Disable node with CTRL+R creates multiple services on node #535 Prevent Unauthenticated SignalR calls from nodes\nAll calls from Nodes are authenticated directly on connection rather than only using SignIn method. Mobile console\nThe *Console has been extended to the mobile view History log of all successful and failed transmitted messages along with related events.\nFrom the Node page users can now access last weeks event Action drop-down menu. This will provide good insight of everything happening on the node. Highlighting in Console\nAlong with filtering users are now able to highlight events of interest. GitHub integration\nYou can now synchronize Scripts in your microServiceBus.com organization with your gitHub Repo! Just follow this simple guide to Integreate with GitHub. Aggregations of this information can be accessed from the portal. Azure device sdk (azure-iot-device-*) has been updated to 1.4.0.\n1.4.0 comes with many updates and improvements for handling re-connect and persistence of messages. Allow ‘node restore’ with parameter specifying customer’s (private) environment uri.\nWhen starting up the node for the first time you can now use -env to specify private or self hosted hubs: Always persist messages on Node \nBy setting the retention period on the Node greater than \n“0”, all outgoing event and messages are persisted on the device until the retention period is exceeded or the available storage is less than 25%. Fixes: Implement retry policy “NoRetry” for Azure IoT. Migrated to 1.3.0 of for Azure device SDK."},{"relativeUrl":"/administrativetasks-list","url":"http://127.0.0.1:4000/administrativetasks-list","title":null,"content":""},{"relativeUrl":"/integration-list","url":"http://127.0.0.1:4000/integration-list","title":null,"content":""}]