Downloading in Depth
Loading Part 1
This text deals with loading files onto the microcontroller. It is a fundamental part of development and so should be well understood. It is mentioned in the MX1 tutorial but there is much more detail in this text.
As the microcontroller (board or IC) is connected to the COM port then all communication is done via that. There is a very simple text loading protocol that allows the transfer of programs written on the pc to get to the board. The ByPic command to use is tload.
It is important to point out that tload does not simply transfer text from the PC into the board but it will compile the text into runnable functions. If there are any errors the loading will stop and the error reported. The following gives an example of copying to a local file and then an example of loading from the internet.
// this is the first program to download onto the microcontroller board function gs_hello(name$) print format$(" Hello %s\n",name$) endf function gs_go() dim j for j = 1 to 5 print j, gs_hello("Fred") next endf
- copy the green URL above into the clipboard(CTRL_C).
- On the editor (not the black screen) use Scripts>Open URL in Clip
- click Ok
- Press F4 (function key 4)
After pressing F4 the BVS screen will show the functions that are being downloaded (just one in this case).
The advantage of this method is that it can be saved locally if required and also edited. There is no need to save the file if this is not required.
The URL or file can also be pasted directly into BvSerial (BVS) by typing .tl (dot tl) in BVS:
This will bypass the editor and load directly. It can also be done from the editor using Scripts>BvSerial>Sends File.
to run the program type gs_go
This forms the basis of the development cycle. Write the program in Pspad, press F4 and test. The next loading tutorial will go through the #options for loading that makes it possible to control the files and how they are loaded.
NOTE: In this section there is an interaction between BV_COMM (the original terminal emulator) and the ByPic firmware. Not all of the options have been fully implemented into BvSerial.
In this section we will look at the #option values of the tload method. This will only work with BV_COMM as it is an interaction between BV_COMM and ByPic. (Update some #options will work with BVS) The options are quite powerful in that it will enable the optional inclusion of other files into the board. In this way standard libraries can be used but if they are already installed then they will not be downloaded again.
The main purpose of this mechanism is for end products where a set of files need to be applied to a particular board. The secondary purpose is to enable a third party program to make sure that all of the functions, constants or globals (items) it requires are in place for the program to run. The files or library files can be obtained form a fixed source – i.e. the internet.
To get a flavour of how this works, have a look at "load_2.bas".
// Example of using a library file as part of a program #option first on #include "http://byvac.com/mBlib/flb/Library/PIC32MX3_Family/BRegisters/MX3_reg_ports.bas" function ld_2() print "TRISB address is ",hex$(TRISB) endf
- Select the green url above the code. Press control C or right click and copy.
- Paste this into the text box on the text transfer dialog, see the picture below. The URL will be different as I am using a local host for this.
- Press send. ** Depending on the internet connection you may have to do this again if you get a time out error as some connections are slow to start but after that they are okay. **
- Type ld_2 and you will see the address of TRISB that was obtained from the library program.
All of the options are explained below but just to explain the operation of this particular file (load_2.bas): #option first was switched on. This means that if any function of a file already exists then that file will not be loaded, so if you carried out this exercise twice then the first time would load all of the functions, the second time would load none because they are already there. The main purpose of this option is to prevent standard library functions from being loaded over and over again – a user can freely include a library just in case it is needed.
The #include option includes the library file that has a list of most of the IO register addresses.
Just to make it clear that the #option mechanism is not part of mB but part of BV_COMM and so these options will not work with any other terminal program.
The file then (load_2.bas) will load the library that consists of a list of constants and the function ld_2() will print out the address on one of those constants.
Text Transfer Options
The following is a list of all of the options available. This relates to version 1.31 of BV_COMM
#include “file or url”
Includes the file as if it were part of the current one. Note that an internet file may take longer than the time out to initialise and so may fail on first attempt. If a URL is specified the full URL must be given including the http:// If there are space in the file specification surround the name with double quotes for example
#option only [on or off]
If this option is set, "#option only on" then as each constant, global or function (item) is loaded then mB will check on the board if it already exists, if it does it will not be loaded again. This is useful if several utility functions are kept in flash and are used by various libraries. If this function is on then reloading a file with the same library will not take up any more space.
#option first [on off]
The option only will check every item on the file. This will only check the first item and if it exists then the whole file will not be loaded. The reason for this option is that it is quite likely that if the first item of a file exists then the rest of the items in the file will have been loaded at some point so there is no reason to check all the rest of the items.
#option echo [on off]
This option will echo back to BV_COMM all the lines that are being loaded.
#option noload [on off]
If this is turned on the file will be sent to the board but will not be loaded into RAM, in case you think this is a bit pointless it can be used in conjunction with openlog ( see later)
All text after this statement will be ignored by mB until either another #comment or the end of the tload session is reached. This is handy for commenting out an unwanted section of an existing file.
#saveto host “filename”
Opens a file on the host saves contents to the file and closes the file. The file is opened as “wb” and so any existing file will be overwritten without warning.
#openlog “filename” and #closelog
The above two commands will open a file on the target and all output will go to the file. Obviously an SD Card must be available and working as that is where the file is saved to.
This can be used in conjunction with 'noload' to download a file onto the SD card or several files. Files from the internet can also be downloaded on to the SD Card this way.
#send “basic command”
Sends a command to the basic interpreter during loading. The maximum length of the command is 80 characters.