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!
The goal of this project is to implement a basic DMX lighting controller using an EFM32 Giant Gecko microcontroller.
So, what’s DMX? DMX512 or 'DMX' is a serial protocol used in the control of lighting equipment. Traditionally for stage light dimming, its use has expanded to laser scanners, fog machines, actuators, residential holiday lighting, etc.
A few milestones were set to achieve the goal:
• Verify my research of the DMX specification: Capture live DMX traffic on a scope using “loopback” DMX break-out terminators (provides access to the signal conductors) between a standalone DMX controller console and a DMX LED “PAR” Can
• Interface to external RS-485 transceiver chip and verify functionality: Giant Gecko STK running USART demo code driving external transceiver -> scope observation of D+/D-
• Develop software to implement simple DMX protocol traffic: Drive minimal spec-compliant DMX packet to transceiver -> verify timing by scope observation
• Demonstrate DMX lamp control in 7-channel mode: Drive 7-channel DMX Universe with GG STK -> verify expected lighting responses by LED “PAR” Can
DMX communication is on a unidirectional network, and a DMX controller can drive between 1 and 512 devices in the serially connected 'DMX universe'. The protocol includes asynchronous serial data at 250 kb/s in 8N2 format and a DMX Packet which equals 8b frame for each channel in the universe.
Figure 1. A single transmission (DMX Packet) includes synchronizing elements and channel data for up to 512 channels Image Source
Figure 2. DMX Packet Image Source
An example of a DMX device is an LED "PAR" Can Lamp, which can be operated in 3 or 7 channel mode.
Figure 3. “Off the shelf” DMX solution
Figure 4. EFM32 Giant Gecko-driven DMX solution
Software: DMX Packet Transmission
DMX Packet transmission was ported from DVK UART RS-232 example. DMX Universe stored in 513B array (StartCode + 512 channels).
Software: DMX Packet Transmission
An array holds 6 sets of data for channels 2-7 of the DMX “PAR” lamp while Ch 1 (Master Dimmer) is left at 0xFF (no dimming) throughout.
Updates to the DMX Universe are then transmitted during the next DMX packet.
DMX Packet: Set # 1
DMX Packet: Set # 2
DMX Packet: Set # 3
DMX Packet: Set # 4
DMX Packet: Set # 5
DMX Packet: Set # 6
EFM32Giant Gecko DMX Control In Action!
This Hack a Gecko project is a result of a "fun hacking session" and are provided as is, free of charge with no guarantees or support from Silicon Labs, to partially or fully show and demonstrate EFM32 Gecko microcontroller capabilities. Get inspired, use at own risk, and build some awesome and cool applications."
This project improves the use of many Bluetooth trackers by removing the need for your smartphone. In effect it’s a Bluetooth-WiFi bridge (using the BLE121LR). Even when your smart phone is out of range you can continue to be notified of your tracker. Other options include turning Bluetooth 4.0 tracker or beacons into a home security device. Additionally, with the built in web service, devices that feature push buttons can now easily lock the door upon your departure, open a garage door, ring a door bell or turn on a light. The possibilities are endless. The best part is that these work even if your phone battery dies! This project will be open source!!
In this episode of my Bluetooth in Action series, we'll have a closer look at installing the SDK, and looking at an example program that comes with it. I'll briefly explain the different files, and what they are for, as well as showing a program structure. You'll see the file that contains the project definition, the hardware and Bluetooth profile files, and then the source code, and also how to use the SDK to compile a firmware.
In the next episode, we'll be looking closely at BGScript, and how to program with it.
Welcome to a new episode of my Bluetooth in Action series. In this episode, I'll be looking at the different ways you can program, or use, the BGM111 module. As you'll see, you have three choices.
In order to understand the different ways of using the module, we first need to look at how Bluetooth modules used to be connected. Bluetooth modules were integrated modules containing a small microcontroller, but you never knew exactly what it was, because you didn’t have access to it. When powered, it would automatically initiate a start-up sequence, read some parameters from flash, and open up a serial port; mostly UART or SPI. From there, your hardware application would “talk” to the module using serial, sending instructions and receiving responses. Once your application had configured the Bluetooth module as needed, the module would then enter a specific mode, where instead of communicating instructions, you would communicate raw data to be sent on the Bluetooth link, and you would receive data from that link.
To be honest, that actually worked pretty well. It was a problem to develop for, though. Most of these adapters used the old-style AT commands, and you had to write your own API. It wasn’t particularly difficult, it just required string manipulation knowledge. The problem often came with what is known as command and data mode. When in command mode, the adapter accepted instructions, and responded to those instructions. Like “Tell me know many adapters are visible”, “Here you go”. Data mode was simple; each byte received on the UART was broadcast to connected devices, and vice versa. One of the most frequent problems encountered was when switching between these two modes; if something went wrong, and you didn’t check, then the next time you issued an AT command, instead of being processed by the adapter, the string would be broadcast to all connected devices, who probably had no idea what you were talking about.
There was another problem to this – end of life management. Manufacturers often brought out new models as they added features, and if your product had a lifetime of ten years, you would almost certainly need to use, and support, several Bluetooth adapters. There would also be a pretty good chance that their AT commands wouldn’t be identical, that you would have to change a few things along the way. After a few years, your code would probably look something like “if device equals this, then do this, else if device equals this, do this, else if device equals yet another device, then do yet again something else, else printf “whoops! Haven’t finished the API yet”. And what about clients that want a specific firmware version for whatever reason, but who need new hardware? Don’t laugh, I’ve been there, it isn’t pleasant.
Luckily, that’s all over, now your application doesn’t need to configure anything, the module itself can embark enough intelligence to take care of all the fine details, and your application can receive analysed and treated data, concentrating on what it does best. In some cases, the Bluetooth module can replace entire applications. So, let’s have a look at how we can use the module.
Programming method number one – BGAPI. The BGAPI protocol was designed to act as a communication method between an application and an external adapter. And while this isn’t exactly programming the module, it is worth mentioning. When Bluetooth modules were external, BGAPI was a way to talk with the module. The API was clearly laid out, and could be used to create your own libraries. It had two major advantages. Firstly, you could use the programming language that you wanted. If for some reason you didn’t want to use C, you could use something else. Since the API was always the same, you wouldn’t be writing a library for a device, but for a family, which brings us to the second point; compatibility. If your current device was end of life, then you would have to change modules. If the module used the same API (and, of course, had the same functionality), then you could simply swap the module for another one, and not change a single line of code.
So, that might be interesting, but since the BGM111 module has both a microcontroller and Bluetooth integrated, why would anyone need the BGAPI? Well, for the second reason, compatibility. If your application already uses BGAPI, you can connect this device, and use the functionalities offered by this module. That doesn’t mean that compatibility is guaranteed; if your original application uses Bluetooth 2.1 with EDR, you won’t be able to use it with a single-mode Bluetooth smart device. If, on the other hand, your application is a Bluetooth beacon, and records the Bluetooth addresses of modules that are close by, then you probably don’t need to change anything.
There is another reason why you would want to use BGAPI. My desktop computer is where I record videos, where I do most of my development… Put simply, it’s where I work from the most. I love having three screens. I also have two laptops, one is a powerful i7, but it still isn’t as comfortable as the desktop. The other is a tiny ultrabook that I only use for writing, it has an 11-inch screen, non-upgradeable memory, but even if it is a joy to use, I can’t use it to create this series. The laptops do, however, have a huge advantage, they both have Bluetooth 4.0 modules. MY desktop also has integrated Bluetooth, but it only has Bluetooth 2.1, I can’t talk to these modules directly, so I have to have a laptop close by. It would be so much easier to have Bluetooth 4.0 directly on my desktop. I could just go out and buy an adapter, but where’s the fun in that? So sooner or later, I’ll be connecting a BGM111 module via BGAPI to my desktop, and using that to talk with the other modules. I think that’s going to be a lot of fun. And since I don’t want to do systems programming, I’ll use an existing Python library, and have something up and running in no time.
Programming method number two - BGLIB. Since the BGM111 is based on a microcontroller, you would expect to be able to program it using C, just like you can with the entire EFM32 range. This is where BGLib comes in, it is an ANSI C implementation that allows you to access all the Bluetooth functionality, while giving you complete control of the microcontroller. Historically, BGLib was designed for external processors and microcontrollers, since at the time, the module would have been external, so it used BGAPI. Today, BGLib still exists, but this time it exists inside the microcontroller, and as surprising as it sounds, it still uses BGAPI. Once again, compatibility is key, there is a system that works exceptionally well, so why not keep on using it?
BGLib has one major advantage. By using a library written in ANSI C, you can create an application in C that has access to every part of your microcontroller or microprocessor; from simple things like activating GPIOs, all the way to FPU commands, and even routines in assembly, while using an optimized library for Bluetooth functions. The best of both worlds.
The BGM111 is no exception to the BGLib philosophy. Instead of BGLib being integrated into an external processor, it can be used directly on the BGM111 itself. It still uses BGLib, so you get to control your Bluetooth radio using simple C commands, but you also have complete control over everything inside the microcontroller, and the Cortex-M4 with FPU has a lot to offer.
Programming method number three - BGScript. If you want to use the BGM111 as a standalone device, then you can’t use BGAPI, and if you aren’t a C developer, or if you are frightened by all the low-level development that goes with Cortex-M programming, BGScript might just be what you are looking for.
[4-2] Let’s face it, C programming can sometimes be a bit daunting. Simplicity Studio is aptly named, but even so, some people don’t want all the fuss that comes with C. You might have an excellent idea for a future IoT killer application, but if you don’t know C, you’ll spend more time debugging than developing, and by the time you get your project out, someone might have beat you to it. Or you might be a seasoned embedded C developer, but you just want to prototype an idea quickly, to see how it reacts. Scripting to the rescue.
BGScript is exactly as the name suggests, a scripting language. It takes away all the hassle of startup code, memory allocation, interrupt handlers, and so on, and lets you concentrate on functionality. It is event driven, that is to say that while the environment does nothing, the script does nothing. It requires specific actions to process data, and those actions can be devices connecting and disconnecting, receiving data wirelessly, or GPIO interrupts, to name but a few.
By using a simple language, you can have an application up within under an hour. The script has simple instructions that can be used to make complex applications. If you are familiar with scripting languages like Python, you’ll be comfortable using BGScript. If you aren’t familiar with scripting languages, don’t worry, it’s easy to pick up.
Check out the next video in this series here.