#BB11 Create an Arduino Library😨 - A Real World Example (Easy)

and welcome back now today we're going to be talking about how to write a library for any piece of Hardware that you might have lying about for example I have this dual digit device here controlled by a shift register yeah yeah let's not get hung up about what it is this mechanism for writing libraries can be used to control any piece of Hardware I'd like to give a big shout out to my sponsor PCB way PCB prototype the easy way let's have a look at their new Superior a plus Advanced PCB here you can find all the details of what their Advanced PCB service consists of and there's a handy comparison table to see the benefits of the advanced PCB service scroll down to the PCB showcase and you can see some examples of what they can do for you just go to their easy online PCB instant quote page and select the advanced PCB option simple if you have advanced requirements for your PCB try PCB way try them now yes indeed and of course libraries are not just used to controlled Hardware they can be used to control code as well for example if you want a library to control string handling yeah well C plus plus and C has libraries for that so it can be used for complex code functions that you don't want to write time and time and time again in your code we'll write a library for it but as arduinites I suspect most of our libraries will be useful for controlling Hardware like the piece you see on my workbench here so let's use that as a very simple example so without further Ado let's look at the sketch written on the Arduino IDE 2.0 and well why we even possibly might think about writing a library so why would I need a library then to control something as simple as this two digit HC 595 shift bit register controlled display and the answer is whilst I was writing the sketch you can now see on screen there that's using the Arduino IDE 2.0.0 by the way it became pretty obvious that some of the code is very repetitive and laborious and you think surely there must be a better way to Output serial data which that device can understand it just goes yeah great that's fine so we're not going to go through the actual code what it does if you if you really want to know what that code does watch the previous video because that explains how we can control that device but in essence we're sending out serial data that is you know pulses online in a certain format that turns into digits on that seven segment display great okay so you can already see up the front there that there's some pins defined we always need to tell whatever it is we're calling these are the pins we're going to use the setup is a little bit more verbose than I'd like I mean look this bit here for example is how we blank the display it's just a little bit verbose why isn't there one command here that just says blank the display yes well our library should give us that now the loop is just a very simple counter it goes from naught to 99 and when it hits the number 42 in the middle of that Loop it just flashes it a few times yeah I mean simple stuff that you might actually want to do in real life if you're displaying an error code you might well want to flash it a few times to draw attention to the fact that something's gone wrong with your idea project look at this particular Loop we can see a it's quite verbose and there's lots of shifts out which is how we send out serial data from the Arduino digital rights and things and then write down the bottom I've written this little routine called flash number which is very repetitive of what we've done before we've still got the shift outs we're blanking the digits yet again here I've already written it once that should really be a separate function and this is how it sends out the same data so that it flashes on screen so all in all there's a few functions there that could just be made so much easier if we had a library and not least there's the actual Hardware considerations now Hardware considerations means when I designed this little tiny unit these little tiny LEDs on there seven segment LEDs are in fact common cathode however when I bought these large ones for the purposes of the demo because I thought yeah it'd be much easier to see those big digits rather than my little tiny ones I discovered quite my chance that it was in fact a common anode device which means the anodes of all the little LEDs on there are all connected together and you think does it matter well unfortunately for the code it does matter because the bit pattern to illuminate some of those seven segment displays is the exact opposite on a common anode device compared to a common cathode so it'd be pretty useful wouldn't it if the library could be told by the way my display is one of these common cathode or common anode do the necessary whatever that is and the person invoking that Library doesn't even have to know what's going on behind the scenes just the way we like it now when you write a library there are two files you need one's a header file with a dot h suffix on the file and the second one is the dot CPP C plus file where all your code resides to support the functions you've told the compiler about in your header file now this here that you're looking at is a header file now I've called my library dual digit underscore 74 hc595.h just trips off the dung doesn't it yes I know descriptive meaningful and most usefully unique I suppose I really should have put RSB somewhere in there just in case somebody else has already written one of these anyway for demo purposes I think that'll do now at the top of your fault yes pragma wants and include the Arduino header because we are writing in Arduino speak C plus plus after all and we need to tell the compiler where all that code is so that's what that Line's doing fine and then we're declaring a class called dual digits yeah exactly the same as the file name let's keep it the same and everything in sync otherwise things get really muddled in your own ad now okay time to address the elephant in the room there it is that big fat elephant yes this is a class as it says we are writing object-oriented code now because C plus plus is object error oriented isn't it that's the whole point about C plus plus versus C well okay one of the points anyway so let's not shy away from the fact that we are now writing a class which is a blueprint for an object and we'll discuss what an object is and how it comes out of a class when we run our little simple sketch our demo sketch which you can see hovering up here ready to go so let's have a look at the class and we said in our previous bit of the video there are some things we want this class to do for it to be useful in controlling that two-digit display so let's open this up and have a look now immediately you'll see that there's the word public here after that class because these are all the functions that your sketch this one up here has access to okay anything listed under public down here yes your sketch has got access to and you can call and do whatever it is you need to do so in here we have our wished list of functions as it were there's no actual code in here remember these are just Declarations of what the function will look like so we'll just skip the first two and come back to those in a minute what we've got is an update Char function we have an update value function send out function and Flash digits function great that's it that's all that the public functions are for our sketch to consume oh one more blank digits yes well blank digits is very useful when we're flashing the digits to call attention to a particular value these I think we can understand as just being functions that do stuff yeah in much the same way as what that Arduino sketch did previously Unwritten in standard C plus plus Arduino speak what about these first two then okay well so we've got the name of the class here under public and we even have a parameter put in here now you need this because this is what's known as The Constructor when you have described what your class looks like in this blueprint that you need to tell the compiler or compiler I would like one of these please as an object I want you to instantiate that as a real thing now in memory so the component goes okay um I'll call that particular function and I'll create you in memory however many bytes it takes to manage this object you've told me some functions that it needs here already and in a minute we'll have a look at some of the internal workings of that class so the compiler does the work for you and it's nothing to shy away from the parameter that we put in here is optional I've decided I'm going to put this particular parameter in here because well I wanted a demo that that's how we can do it but similarly this function here called begin which by convention only is a function that most developers when they're writing classes include to initialize the object to make things easy for the programmer the developer that's you to use it because we need to pass in the data pin the clock pin and the latch pin and what better way is it to do it here sorry what's what's that we could have done it in the construct yes we could have done it in the Constructor we could have added these three parameters up here as part of this instantiation function or we could have moved this one of course down into the begin but there are two ways of doing it six are one half a dozen of the other you can make your own mind up but most developers do put a begin in which you include then in your sketch in the startup to say this is what I want you to do with that object or here are the pins as we're doing here to let you know how to control it in future so that little ball of memory now floating about that describes your objects and the compiler keeps track of that it says okay the values that you're going to pass into me I'll keep as part of this object and keep it all as one contiguous thing this send out well remember when we're updating digits we might not actually want them to just be displayed just yet especially when we're updating an individual character like this we might say put a 4 in the leftmost digit and a two in the right most digits but you can't actually display the value straight away you want to say well first let's update those digits then display it yeah okay and remember there's there's really despite what I'm saying here there's only one way of updating those digits and it's one at a time the least significant first the right most and the most significant the leftmost second it's the only way of doing it so although we've got a function here called update value have a guess how it might do that okay so that's all the public stuff and all this is exposed to your sketch you can call these fine what's the opposite of public land do you think so the opposite of public is private anything that goes in private means it's purely for the workings of this class not to be exposed to the sketch that's calling it this is the internal workings only So within my little Library code here I've got a buffer a two byte buffer I'm remembering the data clock and latch pins that you told me about so we don't lose those and here I'm actually remembering the type of display you've told me you've got whether it's a common anode display or a common cathode display because the bit patterns are different for each they are in fact the inverse of one another but who wants to be concerned all that you just want to say I've got a display it's a common anode and that's it really yeah here are the three pins I'm using get on and do it great that's what a live is there for uh though the um the digits the binary digits that previously we held in a different file are now in here as a private array so this is no longer visible to the calling sketch because the calling sketch should have no use for that at all it's just display just saying display a value get on with it cool finally and not used particularly very much protected which means it can be used within this class and any class that extends this class but we're not even going down that road I'll put it in here for completeness but it's unlikely that you'd ever put that in just don't put it in in future just remove it okay remember this is a demo so this is the CPP file and the very first thing it does is of course include the Arduino framework because we need that here you probably won't if you're writing this in the Arduino IDE it assumes you're using Arduino then we have to include the header that we've previously glared up here just to tie the thing together to say the functions I'm writing here are for that header over there okay and any of the other libraries you might need or I'm using the string Library here but I could equally be using the wire library for example or a crystal seven segment display library or whatever as it happens I only need that one so here are all the functions basically copied and pasted from the Arduino sketch that we saw right at the beginning of this video put in here tied it up a little bit but basically the same let's just have a look at one to see what it looks like so here we have the update Char function now remember every function that you have for your class must begin with the class name and the scope resolution operator which is those two colons there so that's class colon colon name of function then the compiler knows R this is part of that class and not just some random function you've declared somewhere to be used in some other manner here are the parameters that we're having to pass into here mandatory parameters so this update Char which is really update digit maybe it's a bad name maybe I'll change that in the future we're saying this is my character position whether it's zero or one this is the value I want you to put into that one and this is whether or not I want you to include the decimal point so this is a bit validation here just to make sure that we haven't gone silly and said update the 48th character when they've only got two and also we haven't supplied a value like 3896 and obviously the the single digit can only contain between 0 and 9 or 0 and 15 if it's hexadecimal and then if it's past this little bit of validation which makes up the huge majority of this bit of code here we put it into our buffer at the character position with or without the decimal point fine and then it Returns the value zero meaning everything's okay otherwise you get some kind of error returned because we're passing back an integer value so you can check to see whether it worked or not you don't have to check you can if you want so that's just one of the functions that we've got here um the rest call this a lot of times for example the update values that I mentioned how do you think it works well look what it's doing it's figuring out from the value that's passed into it what the tens are the leftmost digit what the units are the rightmost digit and then updating the Char zero and one with those values and with all that the decimal point yeah so we're already leveraging the value of this class by calling its own functions to support other functions cool now there is one particular function we need to take care of this is the Constructor that we mentioned previously so this is the Constructor where it's the class name the scope resolution operator there and the name of the class again and we're saying this is the type of LED that I'm using fine and then we're creating a little memory buffer two bytes that's all it is because we've only got left and right digit two digits and we're remembering the LED type is it common anode or common cathode all right let's not dwell too much on exactly what this is doing because it's very specific to that bit of Hardware isn't it but this Constructor could in fact be empty you might not want to put anything in there perhaps a debugging message as you're constructing it initially to say I've called the constructors you can read it but apart from that you might not want anything to go in there and finally the begin statement I said look we're just remembering the pins setting the pins to output mode because they know they've got to be and uh then it plays around a little bit with the array inverting those bits depending on where on whether it's a common anode or a common cathode type display it just reads them and rewrites them back in the opposite way okay a little bit specific to this Hardware though oh and finally it clears the output here by once again leveraging the value of this class by calling one of its own routines called send out cool I mean there's not a huge amount in this class and to be quite honest once you've written this code and you can build it up this is what I did I built it up one function at a time for example I did not have flash digits and I did not have blank digits in here initially but it came became blindingly obvious in my sketch that I needed that function because I was writing all this huge amount of code multiple times on this cannot be right write it once yeah do not repeat yourself the dry principle otherwise you're just gonna well it's inefficient it looks messy and you're bound to miss bits if you ever have to go back and change it cool so that is effectively the library how do we invoke all that then right so this is my demo sketch to show the power of that Library uh we have to say yes we're running Arduino speak here here's my library that I'd like please wherever I put my library you say well initially you can put those two files the header file and the CPP file in the same folder where your sketch is just for playing about while you're developing it eventually though you'll want to create its own folder in your libraries folder normally a subfold of your sketches and put both of them in there then you can include that library in any of your sketches yeah right so we still have to declare the pins of course that we're using that we use then to pass into our library this is where we instantiate that particular object this is where the compiler says oh I've seen your blueprint of the class you want an actual version of that now constructed in memory for you and that's exactly what it does at that point I've forward declared these two functions that we're going to use as part of the demo then we have our setup that is now remarkably small apart from the two serial begin and print line statements we just say dual digit dot begin data pin clock pin latch pin marvelous so how does it know about this dual digit well because we've instantiated it here and we've decided to call it dual digit at that point you could have called it anything Fred Ralph whatever but make it meaningful don't make it too long because you've got to continually write that in your code because you're referring to it now the loop I've got two examples in here example one goes through a counter of all digits from zero to FF it then displays 42 on individual characters there we have the four there we have the two and we send out the value manually and then we Flash the current value whatever the current value is out there flush it how does the library know what the current value is well remember it's storing in this little memory buffer now what the last value was yes it becomes sort of semi-intelligent doesn't it you'd have to keep telling it what the current value is you don't have to track that value the library does it for you and the second example here is where it displays all the values backwards this time in hexadecimal but as a value not a character so this time it says just display the value two five five two five four two five three and the library goes away and works out exactly what you need as you saw when we had a look at it and finally it flashes the digits again and these are the two little functions here that we're calling so let's have a look at the all values to see how simple it is there it is look we're counting backwards from 255 we're saying update the value with the current count if the remainder is 4 when we divide by 10 put the decimal point out or not simple as that just to prove that it works and then we send out that value because remember at this point here all we've done is updated the value within the libraries buffer not send anything out yet and then we go okay I'm ready for you to display that value now and off it goes and sends out little delay so we can actually see what's happening otherwise it whizzes through in a split second you never see anything so that's all values and all digits the one above it is similar except we update each individual character one at a time with the outer and in a loop okay if I bring back the um desktop there it is still running the old Arduino sketch let's upload this one and let's make sure it works shall we all right compiling uploading right uploaded there we go right so it's now running as you can see it's starting to display hexadecimal values now after 9 abcdf pretty quick okay when it gets to the hexadecimal values on the left-hand digit it becomes much more obvious and when it's finished counting up all this to 255 FF you'll see that it will display 42 a number of times flash it I think I've just I've said flash it five times but at least this time I can say any number of times and it it's more to do with the length of the flash rather than the delay between the flash much more user friendly here we go watch this there we are marvelous so that means now in my future sketches I can import this Library just by saying include Library name don't have to do very much at all apart from tell it which three gpio pins I'm using can to control that actual piece of Hardware the end from then on I just say dual digit display 33 42 69 F4 yeah it doesn't matter it's all abstracted away and that Library will stay like that now until I want to expand its functionality in some possible way so if you want to have some comments down below you've got any questions I'm not quite sure of that but you're going to have to download the code from the GitHub dead easy it comes down as a zipped package you just unzip it and have a look at the code it is very simple yes it does pertain to this particular piece of Hardware but it's a simple piece of Hardware you don't have to write it for that Hardware of course just display stuff in the serial monitor if you want to just create a little tiny Library just to prove that it works um yeah so comments questions queries whatever down below if you thought oh this was mildly amusing and I actually learned something do give it a like up there so I get the old yay hey yes that one and remember if you like these videos subscribe and hit the Bell as you won't hear from me again subscribe and Bell great stuff and I'll see you in the next video I hope you're finding these videos useful and interesting there are plenty more videos to choose and a couple are shown below and if you'd like to subscribe to this channel just click on my picture below and enjoy the rest of the videos thanks for watching

Channel: Ralph S Bacon

Views: 25,713

Keywords: Arduino, Beginners, electronics, C++, microcontrollers, programming, gadgets, ardiuno

Id: mhYuiveM544

Length: 25min 53sec (1553 seconds)

Published: Fri Nov 11 2022