Do-more BRX PLC: REST API Training from AutomationDirect

this is a short training video on how to use the built-in rest api in the do-more bricks plc rest stands for representational state transfer and of course api stands for application programming interface but really all you need to know about it is this feature allows you to utilize a url otherwise known as a uniform resource locator address to read memory locations from the brx plc everyone who uses a web browser uses a url for example the url is the particular.com website you type in to go where you want to go and always begins with http colon slash first of all the rest api web server came about with do-more technology version 2.8 and only in the brick style do more plc's but only the brx plc's that have a built-in ethernet port are equipped with this it's a web server that can be accessed by any web browser using the ip address of the brx plc at the url the web server will return a default web page giving some general information about the brx plc we'll talk about that in a video of its own because you can learn to make your own web pages furthermore the web server on the brx not only serves up a default web page but also has the rest api that allows access to the memory elements in the brx plc via that web browser or any other web client programming package the request is made via a properly formatted url which we'll discuss in a second the response coming back presents the data requested in the popular json data format the rest api can return the contents of any memory in the plc this includes bits numerics strings and even structures but how is the url properly formatted to take advantage of this feature before we get into that it is important to know this feature is for reading only none of the memory locations can be written to using this feature so what is the format of the url necessary to utilize the rest api to get a single element it looks like this the purple sections are the static text required the other colored things in angle brackets are the variables required first is the brix plc's ip address second is the name you provide it can be anything you want it to be third is the brix element name itself thus an example might look like this notice the ip address of the bricks i chose the name of scan count and the element i want to see was a system double work dst 0 which in the briggs plc is called dollar sign scan counter and it's incremented every scan if i type this url in manually in my web browser what would be the result this notice the data value in dst 0 is the value portion of a name value pair called scan count it's presented as a single json object properly contained in curly braces scan count is the name i chose to call it also even though this value is constantly changing this url will only give the value of dst that was read at that moment it will not continually update unless you keep hitting the refresh button in your browser another very important thing to know here is that i don't have to use the raw element name like dst 0. instead i could use the tag name this is also called a nickname in do-more designer that is either automatically assigned in the case of system elements or one that you have previously assigned in your brx plc this would change the example here to use dollar sign scan counter which is the tag name of the system element dst0 the result of course would be exactly the same you need to keep this very important thing in mind because most people when programming a plc utilize tag names extensively simply because it makes more sense to have a familiar name for the elements used rather than the raw less relevant element name itself so what if i wanted to get several non-contiguous elements notice all that is needed is to append another name equals element by using an ampersand the dots at the end here just mean etc so in this example i'm getting five elements separated by ampersands i'm asking for several non-contiguous system data double words dst 0 3 12 18 and 22 the result looks like this again it's a json object but it contains multiple name value pairs properly separated by commas and using the names that i gave each element once again don't forget i could use the tag names of the dsts instead making the example look like this and the result would of course be the same what if i wanted several contiguous elements to get contiguous elements i really have to follow the name equals part with a comma and a count this count can be up to 128. so in this example notice i am getting 10 dst starting with dst 0 and then i am using an ampersand to get another group of 10 x's this time starting with x10 and then four strings starting with ss0 the result this notice here that the contiguous values are given in a json array and since i requested three groups of contiguous values by utilizing the ampersand in my request then the resultant json object has these three arrays properly separated by commas but again make note what if my x10 input element had a tag name or a nickname of let's say conveyor then the url could use the tag name of conveyor instead of the raw element name of x10 always keep this in mind now let's talk about the bricks structure elements which have various members as you may or may not know when you display a structure element in a dataview in do-more designer software for example and not a particular member of that structure there are two formats accommodated there the short format and the long format similarly but not exactly the same way when using a rest api it supports differing responses a short version a long version and one called an all-inclusive version to get a short version you request a particular structure and follow that by a comma s like so in this example i'm asking for the program code block structure dollar sign main and also utilizing the ampersand again to ask for the short version of the structure for timer 6. what happens this this looks like a mess well let's make it pretty by using the popular json pretty print so now we can get this instead some very important things to notice as you can see it returns the structure members of dollar sign main as multiple name value pairs where each name is the actual name of the structure member in real life the same happens to the timer 6's structure these are not all the members but just the short list this time the only difference is using the letter l instead of s which of course stands for long so the example is the same except for the letter l the result this making it pretty you'll notice there are some extra name value pairs added as indicated in red now there's one more and this one asks for every single member of any particular structure notice here the only difference in the format of url in my example is the letter a result this huge big mess every single structure member for dollar sign main is returned and since dollar sign main has 128 stage bits every single one of them are given in a json data format you may also notice at the end of this mess where timer 6 structure members are returned it isn't any longer this is simply because in this particular case there just weren't any more to add to the long version making it pretty it's easier to read and we abbreviated a little bit you'll notice the extra name value pairs once again indicated in red there's one more i want you to be familiar with perhaps i don't want all that math to have to parse through i can get a single structure member just by asking for it using the dot to separate the structure name from the member just like i would enter it in a data view and do more designer software so the example asks merely for one member in each of the structures and as you can see the result is short and sweet so how does one go about enabling this feature in the brix plc the rest api feature is not enabled by default to enable go to the system configuration either via the menu selecting plc system configuration or by pressing the configure button and when you do there is a small box called web server http right here you'll have to enable it and then press the http settings button to see more so here you can see the maximum concurrent sessions by default it's set to four this is the number of simultaneous http sessions the web server will maintain the thing to remember here is that if you make this number larger that each session will consume plc memory and add processing time to the plc scan once the session limit is reached all other requests will be rejected by default the tcp port number for web browsers is 80. in the enable features box various options are available the first is the rest api this must be checked in order for what we have just discussed to work but what are the rest of these options the onboard web server automatically builds several web pages that can be displayed in a web browser the rest of the options here allow you to turn each one of these on or off these web pages will be covered in another video and once you have enabled the rest api you must write that down to the brix plc but now knowing how to use a rest api in the brx plc this begs the question of security can just anyone see what's happening in my plc if you enable this then yes by default anyone on your local network could utilize this feature so what could be done back to the system configuration there is a box right here called server whitelist you'll have to enable it and then press the whitelist settings button to see more there is a lot that we can say about this dialogue which we may cover in another video of its own suffice it to save briefly the function of this white list is to allow access to brics plc resources to certain ip addresses of the network that have been previously identified as safe all other ip addresses will be rejected but enabling this whitelist doesn't really do anything unless you make some changes in this dialog with regards to http and rest api if we put an x in the box then you'll notice the add button at the right is enabled then if you press the add button you can add ip addresses one at a time if they're non-contiguous or ip address ranges to the white list here i enter my pc's ip address for example and then i press the ok button the result is this this now means that the only ip address that can utilize the rest api is my particular pc in this case all other ip addresses that attempt to utilize this service will be rejected be careful here because it makes no sense to enable the whitelist and then have no entry for it in the case shown the only ip addresses being scrutinized are the ones that attempt to use the rest api now since i don't have any of the other services x then no discriminating is going to occur with those services armed with this information you should be able to read whatever you want from your brix plc with any http client whether that client is simply a web browser like chrome firefox microsoft edge or something much more useful like a web client programming package have fun and thanks for watching you