In this episode, we'll look into BGScript development, and see how to create a BGScript program, using variables, functions and calls. I'll show you where to look to get a complete list of functions, and how to add them to your program. Finally, we take a quick look at how to compile a BGScript program.
For this episode, I’ll be concentrating on code only. We’ll create a complete application together in the next episode, but for today, I’ll just talk about writing code. You can use just about any text editor you want to write code; I’ll be using Notepad++, but feel free to choose something else. So, on to BGScript!
There are two documents that you will require for BGScript programming. The first one is the Silicon Labs Blue Gecko BGScript Developer’s guide. It talks briefly about all aspects of the language, and will go into a little more detail than today’s video. Download it and keep it in a folder somewhere, it will be a guide later on. The second document is the BGM111 API Reference Manual. Despite the name, the document not only talks about BGAPI, but also about BGScript, and will be needed to know more about function names and parameters.
BGScript is written in human readable form, and as such, you are free to add in text that is not directly part of the program. These are known as comments. They are used to tell readers who wrote the program, what the program does, and more importantly, to leave some idea as to what your code is doing, or is supposed to do. If you create a library for someone, you’ll want to add comments to tell other people what your code does, and how to use it correctly. Comments start with a hash sign, and everything after the hash sign on that same line is ignored by the compiler. So, let’s try this, hash, BGScript 101 tutorial. There we go, we have our first comment.
Another essential part of programs is the use of variables. There are values in memory that change. To define a variable, use the “DIM” directive. BASIC and Fortran developers will feel right at home here. By writing “DIM”, in lower case, and the name of the variable, you tell the compiler to prepare a portion of memory for this variable. You don’t need to specify the type. The compiler will then allocate a 32-bit memory location for this variable. DIM MyVariable. To create a buffer, that’s to say a variable with multiple data parts, use the DIM directive, and specify the size in parentheses. The compiler will then allocate a certain amount of 8-bit values; the amount that you specified. DIM myBuffer parentheses 10. Finally, to specify data that doesn’t change, called a constant, use the “CONST” directive, followed by the name of the constant, and then it’s value; myconst equals two.
Now to add some code. Code cannot be added just anywhere; it needs to be placed in a specific block. As I said in the previous episode, BGScript is an event driven language. You could say that it’s philosophy is “if this, then that”. If something happens, then I will react to that event, and do something. If nothing happens, then I have nothing to do. There are multiple events; when a connection is made, when someone disconnects, or even when the system starts; these are all events, and code can be written to make the module do different things when these events occur. For example, it is frequent to use the startup event to configure the device and set outputs to a known state, before continuing. To add an event, use the event directive.
In order to write code for an event, you must first tell the compiler what event you want it to handle. Add the name of the event, and any parameters that will be required. So, how do you know exactly what the event name is? Refer to the API document. Let’s I want to add some code to be run during the startup event, and while I do remember what it is called, I can never remember the parameters. So, the API will help us. This belongs in API Reference; system; it is a system event, and the event is system boot. This event indicates the device has started and the radio is ready. Perfect, that’s exactly what I want. A little lower, we have the BGScript event; I’ll copy and paste this into our code.
Let’s have a closer look at what we have written, there is a lot here. The “event” directive tells the compiler that what follows will be code to run during an event. The next word is the event name that we found in the API. After that, we have parentheses; all of the data fed to the function will be held here. Inside, we have the list of parameters; major, minor, and so on. To know exactly what they refer to, have a look at the API, it is all listed. These parameters can then be used inside the event; they often relay important information. For the startup event, data about the hardware version is provided. You can safely ignore these, but for some other functions, the parameters will be essential. For example, the interrupt event will tell you which channel, or channels, created the event. You will have a single event, and it is up to you to create code to locate the channel, and act accordingly.
So this is the start of an event. To tell the compiler that we have reached the end of the code, simply use the “end” directive. Now, when a startup event occurs, that is to say when you turn the board on, all of the code between the event system_boot line and the end line will be executed. This is true for a number of directives; I’ll go into them a little later on. To help make the code more readable, use an indentation; like a tab or soft tab. Let’s add a comment; hash System boot. Since the code is indented, it makes it easier to see that this part of the code is inside something else.
A little more about events. When an event occurs, the code inside the event directive is run. New events will run new portions of code, but only once the module is free to do so. Code inside events should be as fast as possible. I don’t mean to say that you should optimize your code for micro-second execution, the ERF device is fast enough not to need that, but don’t go overboard on different types of code. For example, if you want a LED to blink, don’t tell the microcontroller to stall, or wait. Even worse, don’t use a while statement that would block the microcontroller; events are not interrupted. If code execution never leaves an event, no other events can be processed, and your application will stop functioning.
About the “end” directive. I said there were other examples, and here is one of them, conditional execution. If you need code to be run depending on a result, use the “if” statement, like you would with most languages. For example, if myvariable less than 5, and terminate with end if. Inside that code portion, indented, we can add myvariable equals 2. The end if statement tells the compiler which portion of code is conditional.
Repeatedly writing code is boring. C developers are used to functions, and Python developers are used to DEF. You can also create functions in BGScript; they are known as Procedures. To create a procedure, simply write the procedure directive, the procedure name, and any parameters that will be passed on in parentheses. For example, procedure myprocedure, and we will use info as a parameter. Once again, use the end directive to terminate the procedure. To run a procedure, use the call directive; call myprocedure, and we will use myvariable as a parameter. One thing that is worth noting, procedures cannot return data. If you need to pass data back to the main program, use a global variable.
In the next episode, we'll be writing a brand new application, one with real-world uses. I hope to see you then!