hi i'm michael osman of great scot gadgets and this is software defined radio with hack rf lesson five hack rf1 most of this course is about software defined radio but this lesson is about hack rf1 the hardware platform hack rf1 comes in a cardboard box and inside the box you should find a usb cable and hack rf1 itself hacker f1 has a black plastic injection molded enclosure and at either end of the enclosure you'll find all these various things and i'd like to go through these things one at a time so you understand what they all mean and how to use your hack rf1 now the most important thing you need to know is the usb connector it's a usb micro b connector and the reason it's most important is because hacker f1 is powered by this connector so it doesn't do anything unless you plug in a power source i'm going to plug it in to my host computer and you should see that some of these leds illuminated let's go through these leds one by one and talk about what each one means the first three leds that you should see illuminate when you first plug in hack rf1 are 3v3 1v8 and rf and those are three different power supplies within hack rf1 normally they should all three come on when you first plug in hacker f1 to a power source and under normal use they should all remain on the only reason a couple of them might turn off would be if we implement a low power mode as power saving mode and then while the hacker f1 isn't doing anything you might see a couple of those turn off but if you're trying to use hack rf1 if you're trying to receive or transmit radio signals then all three of those should be on and if they're not all on then that indicates a problem now the next led is called usb and that indicates that the host computer is actually talking to hack rf1 they're communicating over usb and the host computer has configured hacker f1 as a usb device so you might notice that the usb led illuminates just a little bit after the first three the first three leds should turn on very quickly when you plug in the usb connector and power on the hacker f1 the usb led might come on a second later because that doesn't happen until after the usb host has configured hack rf1 and then the next two leds which should be off when you first plug in hack rf1 are labeled rx and tx rx indicates a receive operation and tx indicates a radio transmit operation so you should see one of those turn on when you're actually using hack rf1 to receive or transmit a radio signal so most of the time while you're trying to use hack rf1 you should see four leds illuminated the three power supply leds and the usb led and then you should only see the rx and tx leds illuminate when you're in the middle of a radio receive or transmit operation now those last three leds usb rx and tx are under software control they're controlled by firmware running on the microcontroller within hacker f1 so if you were to install your own custom firmware you could use those three leds to indicate whatever you want but using the default firmware that most people will be using most of the time those indicate specifically usb configuration receive mode and transmit mode now you might notice that all six of these leds are various colors and the colors don't need anything the only reason they're different colors is so that you can distinguish one of these leds easily from its neighbors the each of these leds is a a single color led and their various colors across the row now the other two things you might notice near the leds are these blue buttons the reset button and the dfu button the reset button resets or reboots the microcontroller within the hack rf one way you can reset hack rf of course is to unplug the usb power supply and then plug it back in but it's a lot more convenient and easier on the usb connector if you just press the reset button briefly that reboots hack rf and it will reset and so the host computer has to reconfigure it on the usb bus it's kind of like what happens when you unplug the power supply and plug it back in but it's quicker and easier to press the button the other button is labeled dfu and that's used for firmware update mode but you don't actually need to use it most of the time hack rf1 is able to update its own firmware without having to go into dfu mode the reason we support the view mode is because that's a way that you can unbrick a hack rf if you have a firmware update that went wrong if for some reason your hack rf does not actually enumerate on the usb bus and you never see that usb light come on then that might indicate there's a problem with the firmware and if that happens after you tried to do a firmware update well then you can use dfu mode to recover your hack rf and the dfu bootloader is actually in rom so it can't be overwritten now to get it into dfu mode what you do is you hold down the dfu button while unplugging the usb connector and plugging it back in actually what really matters is that you're holding the dfu button down while you plug in the power supply and if you do that you should notice that the 3v3 led comes on but the other two power supply leds don't come on or at least they don't come fully on and that's a good way to check that you're actually in dfu mode just very quickly the other way to get into dfu mode is i'll just reset it here so now it's in normal mode the other way to get it into dfu mode is to hold down the dfu button while you press and release the reset button then you can release the dfu button and now hack rf1 is in dfu mode either way whether you whether you hold down dfu during a reset or if you hold down dfu during initial power on then hack rf1 will start up in dfu mode which is using a rom bootloader and you can use a special piece of software on your host computer to actually install hack rf firmware on hacker f1 even if there is no currently functional firmware on the device now i'll just press reset again and it should actually reboot the regular firmware and be back into the normal mode the dfu button doesn't actually do anything except during reset or during initial power on so it is available to you if you are interested in making your own custom firmware for hack rf1 you could actually use that dfu button as an input to your firmware because it doesn't do anything normally it's only during reset that it matters by default now the other thing on this end of hacker f1 is the antenna port and on the other end we have these two ports clock in and clock out all three of these are similar connectors let's take a look at them they're sma connectors and they come with these red plastic caps that are protective caps it's a good idea to leave those on if you're not using the port so for example these clocking and clock out ports i don't use very often so i usually have them covered by the red cap these are sma connectors all three of them and you might have seen similar connectors on wi-fi equipment for example it's very popular on wi-fi equipment to have rp sma now rp sma is different than sma sma has a female connector that is the connector with external threads the threads are on the outside here the female connector if you look inside has a female connection in the inside and then the other connector that mates with this one has a male pin in the middle and an rp sma connector has them the other way around so the female connector or the one with the external threads actually has a little male pin inside it's a little bit confusing that they have these two different styles of connectors that are almost identical except they change which side has the pin internally so be careful that when you're selecting equipment or antennas or cables to plug into the connectors on hack rf1 be careful that you use sma connectors and not rp sma connectors because an rp sma might appear to actually connect correctly but there will be no internal connection because neither side will have a pin and that's a very annoying problem to have because it it can be hard to troubleshoot because it looks like everything's connected but then there's no actual internal connection so be careful of that now the sma connector uh here that's labeled antenna is the antenna port or you can think of it as the rf port you don't have to connect an antenna to it but you should have it connected to either an antenna or a cable going to some other rf equipment one antenna you might use is ant 500 which is just a simple telescopic antenna this is a good starter antenna for hack rf but realize that there's no there's no one antenna that is good for every application that you might use hack rf1 for this is just a good antenna to get started because it is a very simple telescopic it and because it's telescopic it can operate over a pretty wide range of frequencies and it has an sma male connector that allows you to connect it directly to the hacker f1 without any adapters so be sure that you do have an antenna or something connected to the hacker app at all times when you're doing receive or transmit now if you're ever attempted if you're ever tempted to not have an antenna connected at all what you should do is get one of these little dummy loads and this is just a little sma mail plug that has a 50 ohm load within it this just screws right on the sma connector and it allows you to use your hack irf1 safely even with no antenna attached so that's very important never never use your hack rf1 for receive or transmit without having something connected to the rf port it should be a dummy load or an antenna that is suitable for the frequencies that you're working with or a direct connection to rf equipment now if you are using a direct connection to rf equipment be aware of the maximum input and output power levels that you can find on the hack irf wiki it's very important that you don't exceed those limits or else you might damage the hack rf1 now the other two ports on the other end also sma connectors are clock in and clock out and these are for clock synchronization between multiple hack rf1s so for example you can take two hack rf1s take an sma cable and connect it from the clock out of one hack rf1 over to the clock in on the other hacker f1 and then the their clocks will be synchronized which is useful for certain applications now that only matters if you have multiple hack rf ones or if you would like to take your single hack rf1 and would like to synchronize it to a particular external time source for example you might have a gps disciplined oscillator or you might have a rubidium frequency standard or something in your lab that provides a more stable clock source than the crystal that's with within hack rf1 for example and if you do all you have to do is take a 10 megahertz signal and connect it to the clock in and the hacker f1 will automatically synchronize to that external clock it's always looking every time actually it's when you start a receive or start a transmit operation every time you start an operation a radio operation with hack rf1 then it checks to see if there is a 10 megahertz signal on the clock in port and if there is it synchronizes to that signal and if there isn't it uses its own internal crystal now the signal that you need to give it on the clock in port is a 10 megahertz square wave ideally and it should vary between about 0 volts and about 3.3 volts so it's a 3.3 volt square wave and that's exactly what you should see on the clock out port of every hacker f1 so you can connect them directly together from one clock out to the other's clock in or you could connect one or more hack rfs you could take their clock in and connect them to a single source a single time base for all of them most of the time for most applications i don't use those ports and so i just leave the red protective caps on those sma ports and i don't worry about them now let's talk about how to use hack rf1 a little bit and and a little bit about the software that is available for hack rf the hack rf project provides two different software packages and they are called lib hack rf and hack rf tools now lib hack rf is a library that allows other software to communicate with hack ref so for example this is how gnu radio communicates with hack rf is through libhack rf hack rf tools is a small software package that provides some command line tools for working with your hack rf let's get familiar with those a little bit the first command you should know is hack rf info and if your hack rf is plugged in and you type hack rf underscore info you should see that it finds that hack rf unit and it tells you that it's a hack rf1 and it tells you the firmware that is installed in this case it's 2014.04.1 which is from a release package you might see that your firmware says get something or other which is telling you the particular git commit from the from the source code repository but if you install firmware from one of the release packages then your hacker f1 should tell you when you use the hackerref info command that it is running that particular release now the next command i'd like you to know is hack rf transfer and i'll just type it here and show us help output there there are quite a few different options now this is a small utility that you can use from the command line to transmit or receive data so if you receive a if you turn the hacker f1 on into a receive mode using the hack rf transfer command then data will stream over the usb connector and into a file that you specify and if you use transmit mode the minus t option then you will specify a file name and that the data in that file will be streamed over usb to the hacker app and then turned into a radio signal out the antenna port now there are a whole bunch of different options here for configuring the radio section and turning on different gain stages and all sorts of different things but let's try this out a little bit and i'm going to type hack rf underscore transfer and i'm going to tell it to [Music] do a receive operation and put the data into a file called slash dev slash null and if you're on a linux system you should always have a file called slash dev slash null it's a special file and that just throws away everything that you give it so this is just a quick test to make sure that our hackrtf can transfer information to us let's give this a try now it says stop with control c so that's what i'm going to do in a few seconds here i'll just hit ctrl c and i'm done now you should notice that the default sample rate that it set to was 10 million hertz or 10 million samples per second and i got up an average of 20 million bytes per second from the hack rf and that's normal you should see two bytes transferred for every sample because a sample is made up of two two values each of which is a signed 8-bit integer assigned 8-bit integer assigned char and that's the actual data format that's used over the usb connection of hack rf and so the hacker rf transfer utility is just a simple way to take the raw data that comes over usb and put it into a file or to take data from a file and transfer it over usb to the hack irf so in this case we just verified that everything was working correctly uh although the hack rf digital section is working correctly and giving us 10 million samples per second and if we want to we can change the sample rate using the minus s parameter for example if you wanted to find out does your usb connection on your host computer actually support 20 million samples per second if you type minus s 20 million on this hack rf transfer command now we'll be operating at 20 million samples per second and we should see that we get an average of 40 million bytes per second because that's two bytes for every one sample and sure enough on my com on my particular computer on this particular usb port i can get that 40 million bytes per second and that means that the hecariff is able to operate on this computer at its maximum sample rate of 20 million samples per second now that's the advertised maximum sample rate but i found that on at least some host computers and with some hack rfs at least i am able to operate at 21 and a half million samples per second and if you do that you should see that you're operating that you're getting 43 million bytes per second that's the absolute maximum pretty much that i've seen work reliably on any host computer now some host computers won't be able to operate that fast and it could have to do with the speed of the cpu but more likely if you're just using the hack rf transfer utility like this more likely that would indicate that there's a problem with the usb connection itself the usb host controller within the pc might not be able to operate that fast or there might be other usb devices on that bus inside the pc that you can't see and they may be slowing down the available throughput for hack rf so you might find and and this is a good way to find this out you might find maybe your particular usb port only allows you to operate up to 16 million samples per second and hack rf transfer utility is an easy way for you to find this out and it's a good way to find it out because it is only exercising the usb connection if you are writing the samples to slash dev slash null then you're actually not saving the samples anywhere you where you're discarding them and so you're not you're not requiring your cpu to do anything with those samples so it makes it uh it kind of it isolates any problems you might have with a usb connection from problems that you might have with your cpu keeping up and it allows you to determine exactly how fast your usb connection is able to go now personally i've had i've had computers i've had a laptop for example where on one usb port i could get 20 million samples per second and on a different usb port i was only able to get 16 million samples per second you may have various different maximum rates that you find that different usb hosts are able to achieve but in general you should unless you're trying to connect to a very busy usb port or you're connecting to a port that's broken or doesn't support high speed usb as long as the port that you're connecting to is functional and not too busy you should be able to get at least 10 million samples per second which is the default transfer rate with hack rf transfer you should be able to get at least 10 million samples per second with pretty much any usb port and the hacker f transfer utility is a way to verify that now again i want to look at the options here just a little bit if we did the same thing only use the minus t transmitting dev null doesn't make any sense but you could transmit dev0 for example or you could transmit uh data from a file and the data format as i mentioned is two two eight bit signed integers for every sample we'll talk about why there are two uh two integers per sample in the next lesson quite a bit now there are a number of different command line switches like setting the frequency and if you want you can use these options to set the intermediate frequency the local oscillator frequency and the image reject filter selection normally you wouldn't do that this is just a way to kind of override the default tuning algorithm that's within hack rf1 in the future we'll talk more about the internals of hack rf1 and why and how what these exact options mean and what they do inside hack rf most of the time you should use the minus f option to set the frequency now the amp enable option enables the rf amplifier notice it says rf amplifier and so you might have noticed for example in the osmocom source in gnu radio there is a rf gain setting and that rf gain setting we set to zero zero db i think when we were doing an example the other day now in in hack rf transfer you can notice that this is actually set to either one or zero you either enable or disable the rf amplifier there are only two settings for that particular gain stage and that's the stage that's closest to the antenna and so normally and then nominally that gain stage gives us about 14 db of gain although it the amount of actual gain varies by the frequency range so if you set that to i think 10 db or higher in the osmocom source then it will enable the rf amplifier if you set it to 0 in the osmocom source it will disable it now here with the hackerrf transfer utility we simply type minus a0 or minus a1 to enable or disable that gain stage there's also this antenna port power control now normally antenna port power is off which means there's no dc on the on the antenna port there's no direct current power supply there but it's possible to enable a small amount of power on the antenna port that'll that could allow you to use an active antenna for example like there are gps antennas that are compatible with hack rf1 that can be powered by hacker f1 if you use this option and then we have these other gain options and these are different gain stages and these relate to the the other game options that you might have noticed in the osmocom source in gnu radio minus s lets us set the samples per second minus m lets us transfer a particular number of samples so if you only wanted to transfer one second for example and you were operating at 10 million samples per second then set this to 10 million otherwise it will just continue until you hit ctrl c and this minus c option is new it lets us transmit a cw signal or just a constant carrier which is useful for for various testing testing uh states that you might want to put the hack rf in and the minus b option lets us set the baseband filter bandwidth we're going to talk about that more in the future but and this is also something that you can control from the osmocom source in gnu radio but the default notice is less than the sample rate in hertz so whatever you choose for your sampling rate it's going to automatically select the uh the filter the baseband filter that that is just slightly under your sample rate so that's just that's the default and normally that's fine for most applications but we'll talk in a future lesson more about when you might want to use a different baseband filter value now the other utilities that are good to know are the utilities that are used for updating the firmware in hack rf now if you type hack rf info you'll see the firmware version that is installed on your hack rf and in this case this one has 2014.04.1 and that's not actually the most recent version that's available the most recent version available right now at the time that i'm recording this is 2014.08.1 so let's update the firmware now i'm going to use a copy of the release package and this is actually a file that i've that i've downloaded that is the release package for hack rf now if you're using the pen to iso the most recent version that's coming out right about now actually has the contents that we'll need on the iso itself so you won't have to download the release package but you can always download the release package the most recent release and find the files that you'll need for doing a firmware update so i'm going to extract this hack rf release package and look at the contents here i'm going to go into the firmware bin directory these are the firmware binaries and you can see that there are some firmware binaries for hack rf1 and some for hack rf jawbreaker which is the beta platform and then there's also this cpld configuration file that we'll work with in just a moment the first thing i'd like to do is to use the hack rf spy flash utility this is another tool that's part of the hack rf tools package and i'm going to write to the hack rf the file hack rf1 usb rom to ram.bin so just remember that rom to ram and the reason it's called rom to ram is because we write this file to the flash that is on the hack rf and then when it boots up it actually copies it from flash to ram and then executes it so this particular this particular binary is has the code in it that allows it to load itself into ram as opposed to this other one which only is for use during recovery operations using dfu mode [Music] so i'm going to write this file and it only takes a few seconds now it's done now if i type hack rfinfo you should see i'm still running the old firmware because i haven't rebooted the hackrrf1 and i haven't gone through that process of copying having the firmware copy itself into ram and execute so i'm going to hit the reset button on my hack rf1 and now if i type rfinfo look at that i'm running 2014.08.1 that's how easy it is to update the firmware now there is one other step though that you should take and that is updating this the configuration of the cpld that's the complex programmable logic device on hack rf1 remember there's this other file here hack rfcpld default anytime you see an xsvf file that is a configuration file for the cpld and this is the cpld is a chip on hack rf1 that is between the microcontroller and the analog to digital converter and digital to analog converter and it provides some interface functions in between those two and from time to time there may be a new version of the cpld configuration that comes with a particular release of hack rf software so in this case there is one so i'm going to run the hack rf cpld jpeg jtag cpldj tag utility with a minus x option and give it a hack rf cpld.xsvf and i will run this and it tells me to wait until right is finished and sure enough it tells me right it's finished and it's telling me to power off and disconnect the hack rf now in the future this may actually reboot itself when we do a cpld update it might reboot itself when we do a hack rf spy flash update but right now in both cases i have to reset the hack rf to actually activate the new code so now i've reset the hack rf and if i run hack info it tells me the firmware version note that it does not tell me the cpld version so it's very important that you do update the cpld to the latest version when you are when you update the spy flash or the actual firmware to the latest version you have to remember to do that so do both and you'll have your hack rf running the latest software the latest firmware and the latest cpld code and that will go along with the latest software that you have installed on your host computer i'll save an in-depth discussion of the internals of hack rf1 for a future lesson but i hope that getting familiar with the externals and with some of the software that's available for hack rf was useful for you it can certainly be useful to use those command line tools for troubleshooting your hack rf1 or for performing firmware updates now there's one thing about the inside of the hack rf one that i would like you to know about right now and that is the rf amplifier that i mentioned when we were looking at the hack rf transfer utility now the rf gain stage or the rf amplifier is right next to this antenna port it's right here and there are actually two rf amplifiers there's one for transmit and one for receive and then there's a third path that just is a bypass path that allows you to completely bypass those amplifiers and operate either in receive mode or in transmit mode uh without that amplifier active so if you set that amplifier setting to zero or if you set zero rf gain to zero in the osmocom source or sync in gnu radio then you will disable that amplifier stage completely and that's how i recommend that you operate most of the time unless you need that extra boost for a particular application and the reason i want you to know about it in particular is because it's right next to this antenna port there's no filter between the antenna port and that gain stage so for example if you were receiving fm radio stations in gnu radio and you turned that amplifier on and you happen to be in close proximity to a high-powered amplifier running at say two gigahertz completely different frequency than the fm radio stations that you're trying to receive that are that that rf amplifier stage is actually receiving that 2 gigahertz signal and trying to amplify it before it gets filtered out later in the received chain in the hack rf so be aware of that that you could potentially overpower a gain stage you could potentially damage an amplifier in that gain stage if you don't uh if you're unaware of that and if you were to if you were to exceed the power limits of hack rf1 so some tips just to keep your hack rf1 safe be sure that you always operate with an antenna connected or a dummy load connected or a cable to some rf equipment connected and usually if you do use a cable you'll probably have an attenuator that you'd want to put in place be sure to check out the the wiki and look at the power limits of hack rf and that way you'll know how much attenuation you might need when you directly connect equipment to hack rf but if you always use an antenna or a dummy load and you're careful and you don't you don't activate that gain stage except when you really need it uh then your heck rf should last quite well and everything should work but the most sensitive part that you should probably be aware of is that gain stage right by that amplifier so be aware of that and i hope to see you next time for lesson six