GCBASIC documentation

This section will provide some insights into what the compiler does

How does the compiler cope with read only registers in the Chip Family 12 range?

Within this chip range the Option register is a write only register. Reading the register is not permitted.

GCBASIC needs to update this when the user wants to change the configuration - the Sleep process is an example of a user change.

The compiler handles this by the creation of the Option_reg byte variable. This byte is created by the compiler to manage the required write process.

The Option_reg variable is a cache that compiler will create if any bits of option_reg have been set manually.

If the user changes any of the bits in a program, then the compiler will find any uses of the option instruction and insert a "movwf OPTION_REG" immediately before the option instruction to cache the value in the buffer.

If Option_reg bits aren’t set individually anywhere, then option_reg doesn’t get created, and nothing special is done with the option instruction.

Essentially the compiler maintains a special variable and manages the whole process without the user being aware.

How does the compiler cope with the TRIS register in the 10f products?

The compiler ensures that a TRIS cache matches the actual TRIS register. The TRIS cache is a byte variable called TRISIO. The TRISIO cache is required as TRIS is a write-only register.

All ports default to input ( where all TRIS bits to 1) on reset. Therefore, this is assumed to be the value 255.

TRISIO is updated when required by the user code and then used in the writing to the correct register.

The example user code and the associated assembly shows TRISIO cache in use. This method complies with datasheet.

User Code

ASM

Anywhere that an individual TRIS bit is set/cleared by change the port direction, the bit in the cache is changed and then that gets written to the TRIS register.

Forcing the ASM to contain comments

It may be useful to force comments into the ASM file. The verbose mode of creating the ASM will include ALL the source program as comments but it may be useful to have specific comments in the ASM to aid the understanding of code or to support debugging.

To force an assembly comment use the following:

Where the comment will be placed into the ASM file.

Example.

The source file contains the following, where the comment text is OSCCON type is 100

The generated assembly will be as following - this assumes verbose mode is not selected.

Constants, variables, subs and function and labels

GCBASIC uses a single namespace. A namespace is the set of names used to identify and refer to objects of various kinds.   In GCBASIC these can be constants, variables, methods, and labels.  Wwhere a label is a true label like the start of sub, function or macro.   A namespace ensures that all of a given set of objects have unique names so that they can be identified.   This organises constants, variables, methods, labels etc into a single list - the single namespace.

The namespace includes all libraries and source GCBASIC source files.    If using MPASM this expands to chip specific INF file.   If using PICAS then all of the PICAS toolchain including non-chip specific files.   There are changes already in place to resolve this issue for PICAS as HEX and LINE are reserved with PICAS toolchain and these conflict with GCBASIC methods.   These are automatically resolved by the GCBASIC compiler.

So, given that a constants, variables, methods, labels etc are number, the compiler does not know if that is a constant, a variable, a method, or a call to a label. Some are use cases using a constant called NORMAL follow.   NORMAL is defined as a constant with 0.  

#1. Code segment

The compiler will issue no error.   The compiler will assume the following and will do as instructed.   Call normal - this calls normal which has a value of 0

Resulting ASM

#2. Code segment

The compiler will issue no error.   The compiler will assume the following and will do as instructed.   Call normal() - this calls normal which has a value of 0

Resulting ASM

#3. Code segment

The compiler will issue an error message.   The compiler will try to resolve the constant normal to a sub but it cannot as it is a value of 0.

Resulting ASM

#4. Code segment

The compiler will issue an error message.   The compiler will try to resolve the constant normal to a sub but it cannot as it is a value of 0.

Resulting ASM

#5. Code segment

The compiler will issue an error message.   This tries to assign a value to the object.

Resulting ASM

#6. Code segment

The compiler will not issue an error message.   The compiler will goto (same for jmp) to the value of the object.

Resulting ASM

The compiler can be controlled, in terms of the default startup library routines.  This may be required to implement a specific control function, or, to disable a default startup behaviour.

Scenario #1:

You have a new LCD.  The GCBASIC LCD routines fail to initialise.  You want to write your own LCD initialise routine, but you want to ensure the GCBASIC standard INITLCD() does not operate before your own LCD initialise routine.  How to do this?

Scenerio #2:

You want to write your own INITSYS routine.   You can add your own routine to initialise the microntroller but the default INITSYS would always be called in the ASM.

In the first sceneria the approach would be to redirect the GCBASIC standard INITLCD() to myInitLCD using #define INITLCD myINITLCD.   However, prior to the latest build, this would fail to work.  The reason for the failure to redirect to your new routine is the #startup INITLCD directive.  The #startup directive was essentially hard coded and all the #startup(s) could not be changed.

In the second scenerio the ASM call to INITSYS is also hard coded.  And, you could trick the compiler to call your own initialisation routine but this was not easy and not intuitive.  

The new build now supports the updating of the #startup(s) with your own routines, or even to cancel #startup(s).

Examples:

The compiler will search for all #startup(s) and update across all sources (libraries and includes).  LCD.H is just an example.

#DEFINE INITLCD myINITLCD // This will change any reference in the LCD.h #startup INITLCD to #startup myINITLCD.

#DEFINE INITLCD // With no second parameter would cancel any #startup in LCD.h.

#DEFINE INITSYS myINITSYS // This will change the default INITSYS to myINITSYS.

#DEFINE INITSYS // This will remove the INITSYS from the initialisation of the microcontroller.

Example to change LCD initialisation

Example to replace INITSYS

Scripts can now change the #startup.   You can add a script to change the behaviour dependent on a specific condition ( the existant of another constant).

In user program

Supported within LCD.H

will generate ASM like this…​

This new capability to give you more control of the compiler.

For more help, see: #define, #startup

So, you have brought some ATtiny88 breakout boards online.   They are advertised as Nano equivalents but are inferior to the Nano in having low RAM (512 bytes vs 2048) and missing some other features.   Specifically the lack of a USB comport for programming.  

The ATtiny88 USB interface only works in Arduino IDE with some tweaking, and, you are not in the mood for learning how to write sketches after being in the GCB environment for years.  

This is an all-in-one tutorial for programming the ATtiny88 via AVRdude using GCB.  

The process described will create a new programmer entry in the GCB Programmer Options to fully automate the compile & program progress.

The Process

Enter the sample code here into GCB IDE

Now you can select "Hex/Flash" to upload the code to the Attiny88.   If all goes well the LED should blink on and off every second

About Inputs and Outputs

Most general purpose pins on a microcontroller can function in one of two modes: input mode, or output mode.

When acting as an input, the general purpose input/output pin will be placed in a high impedance state. The microcontroller will then sense the general purpose input/output pin, and the program can read the state of the general purpose input/output pin and make decisions based on it.

When in output mode, the microcontroller will connect the general purpose input/output pin to either Vcc (the positive supply), or Vss (ground, or the negative supply). The program can then set the state of the general purpose input/output pin to either high or low.

GCBASIC will attempt to determine the direction of each general purpose input/output pin, and set it appropriately, when possible. GCBASIC will try to set the direction of the general purpose input/output pin. However, if the general purpose input/output pin is read from and written to in your program, then the general purpose input/output pin must be configured to input or output mode by the program, using the appropriate Dir commands.

Example of dir commands.

Microchip specifics for read/write operations

For the specific ports and general purpose input/output pins available for a specific microcontroller please refer to the datasheet.

To read a general purpose input/output pin, you need to ensure the direction is correct DIR Portx IN is set (default is IN) or a specific set of port bits. Where uservar = PORTx.n can be used.

Examples:

To write to a general purpose input/output pin, you need to ensure the direction is correct DIR Portx OUT for port or a specific set of port bits. Where PORTx.n = uservar can be used.

Examples:

ATMEL specifics for read/write operations

Using a Mega328p as a general the following provides insights for the AVR devices. For the specific ports and general purpose input/output pins available for a specific microcontroller please refer to the datasheet.

To read a general purpose input/output pin, you need to ensure the direction is correct DIR Portx IN is set (default is IN) or a specific set of port bits. Where uservar = PINx.n can be used and therefore to read data port use uservar = PINx.

Examples:

To write to a general purpose input/output pin you need to ensure the direction is correct DIR Portx OUT for port or a specific set of port bits. Where PORTx.n = uservar can be used and therefore to write to a data port use PORTx = uservar.

Examples:

Setting Ports and Port.bit

You can set a port as shown above with a variable, or, you can set with a constant or any combination using the bitwise and logical operators.

The following is also valid - read a port.bit and then set port.bit with a variable or port value. As shown below.

The user code above may cause issues with glitches when the read and write operations occurs. Let us look at the generated assembler.

To resolve any glitches add #option Volatile to your user code.

This option provides the following assembler resolving the glitch issue.

See also Dir, #Option Volatile

About Microcontroller Configuration

For PICs

This section applies to Microchip PIC microcontrollers.  For AVR and LGT microcontrollers see the sections below.

Every Microchip PIC has a CONFIG word. This is an area of memory on the chip that stores settings which govern the operation of the chip.

The following asects of the chip are governed by the CONFIG word:

The exact configuration settings vary amongst chips. To find out a list of valid settings, please consult the datasheet for the microcontrollers that you wish to use.

This can all be rather confusing - hence, GCBASIC will automatically set some config settings, unless told otherwise:

Note that these settings can easily be individually overridden whenever needed. For example, if the Watchdog Timer is needed, adding the line

This will enable the watchdog timer, without affecting any other configuration settings.

For AVR

This section applies to Atmel AVR microcontrollers.   Generally, Atmel AVR microcontrollers do have a similar configuration settings, but they are controlled through "Configuration Fuses". GCBASIC cannot set these - you MUST use the programmer software.

The exception to the general case are the ATTiny4-5-9-10 and ATTiny102-104.   These microcontrollers have software selectable frequencies for the following frequencies:

Therefore, you can use ( an example )

For LGT

This section applies to LGT microcontrollers.

All LGT microcontroller have software selectable frequencies for the following frequencies:

Therefore, you can use ( an example )

Using Configuration

For PICs only.

Once the necessary CONFIG options have been determined, adding them to the program is easy. On a new line type "#config" and then list the desired options separated by commas, such as in this line:

GCBASIC also supports this format on 10/12/16 series chips:

However, for upwards compatibility with 18F chips, you should use the = style config settings.

It is possible to have several #config lines in a program - for instance, one in the main program, and one in each of several #include files. However, care must then be taken to ensure that the settings in one file do not conflict with those in another.

For more help, see #config Directive

Description:

The drivers for windows x86 and x64 correspond to the USB LIBKWIN capability of GCBasic for supported PIC microcontrollers.

For security reasons, in Microsoft windows for a driver to be installed, it is necessary that it be digitally signed by Microsoft.

Microsoft did make a special “Test” mode for developers to install MANUALLY unsigned drivers for debug and testing, being a technical advanced and not user-friendly procedure; at the same time the windows developers make efforts to disable the capability of doing this in an automated fashion by the concerns of being used as a vulnerability of the operating system.

This scenario will make installing test drivers difficult and frustrating for the uninitiated, at the same time for a useful Hobby project it will be not practical to make end users to take all this drama.

This driver installer method resolves the constraints imposed by the Windows operating system, and, therefore will allow you to install the drivers in the easiest way possible, almost like any driver of a well-known company.

Usage:

1 - Open the installer, it will request admin rights.

2 - Navigate thru the wizard to automatically extract the driver files (there aren’t any options to select).

3 - At the end of the wizard, after you click the exit button, the system will restart automatically

4 - After restart and login in to your user account, a window will inform you that the driver is not signed and you will be asked if you want to install the driver, please allow it.

5 - when the driver has been installed, the computer will restart automatically.

Secure Boot Enabled, Boot menu steps

USB Driver details

The driver uses the following USB flags.

For others, need to modify and recompile the USB library.

USB_PRODUCT_NAME and USB_VENDOR_NAME can change without problem (windows device manager will show the name reported by the hardware not the driver

Tested on (but not limited to)

This section discusses the different types and sizes of data variables used by GCBASIC, and how they are interpreted or handled by GCBASIC methods.

The section also provides an insight of which type of variable to use and when.

What variable sizes are suported by GCBASIC?

GCBASIC implements support for Bit, Byte, Word, Integer and Long Variable Types, all of which are described below.

Supported variables are Bit (1 Bit), Byte (8 Bit), Word (16 Bit), Long (32 Bit). GCBASIC does not support decimal numbers.

Bit is used as a Flag or a Port Pin and has two states which may be:

other complementary states depending on how your application interprets and handles the data.

Byte is the most common size in 8 Bit devices and could represent a Number, an ASCII Character, a Port, two Nibbles (as used by Hex or BCD number systems), an Internal Register, an 8 bit Variable or any user defined collection of to eight Bits such as a group of flags.

Word is normally used for its Numeric value. 16 Bits will allow it to store Numbers from Zero to 65535 which is large enough to store the product of any two 8 bit Bytes without overflowing.   However, it is not confined to being used as a numeric value.   A Word may be used in any manner that your application needs depending on how it interprets the 16 Bits of data. Examples may be a memory address or a data pointer.

Long is for situations where Values exceeding 65535 have to be handled and has a range of zero to 4294967295 (2^32-1).  It is rarely used in 8 Bit devices but is invaluable on the rare occasions that it is needed.    The Millis() is an example that uses the Long Data Type to handle time periods of up to 50 days.

All of the above can be considered to be Integer Values of varying magnitude as they can hold non Fractional Positive Whole Numbers, but try not to confuse Integer Values with the Integer Variable Type, they are complementary but separate concepts as you will see below.

An integer is a whole number (not a fractional number) that can be Positive, Negative, or Zero.

In your application there may be a need to be able represent Negative Numbers in our variables and that is where the GCBASIC Integer Variable Type is useful. An Integer Variable is similar to the Word Variable as they are both 16 bits.    The difference how the GCBASIC compiler interprets the data bits that it contains.

The compiler will treat a Word Variable Type as a Variable that can store the values 0 < 65535 but it will see the Integer Variable Type as a Variable that can store values of -32768 < 0 <32767.

Variable size

Each type of variable is defined in various bit lengths, in this case GCBASIC these are:

All four of the above are number types are true Integers.   In that they are representations of a integer non fractional number as follows:

But, they can only represent positive numbers.   In Mathematics there is a need for an Integer that can be Positive, Negative, or Zero.   Note that Zero is always a Positive Whole Number.

Two’s Complement

To take the Two’s Complement of a number it is inverted then incremented:

The increment, of adding 1, has two effects, it avoids the possible creation of a negative zero as a value of 1000000 would be seen as -128 and it allows subtraction to be achieved through addition.

If MyVar contained a value of 1 the 8 Bit representation would be:

The NOT will make it

Note that the Most significant Bit is now 1 so as a signed value it is negative.

The increment will result in a value of:

So Minus one using an 8 Bit representation in Two’s Complement notation is 11111111

Let’s test it by adding -1 to plus 3

We have successfully subtracted 1 from 3 by adding Minus 1 to 3 and obtaining a result of 2.

Notice that while a Byte is normally used to represent 0 < 255 by making the MSB (Most Significant Bit) into a sign bit the maximum value is now 127.   A signed 8 Bit integer can represent numbers in the range -128 < 0 < 127.   That is still 256 values including Zero but they can now be Negative or Positive numbers.

The benefit of the two’s complement method is that it works for any size of variable:

All of the above will result in a Negated version of the original contents.

But not all, in fact relatively few, methods of a microcontroller require negative values so in situations where negative values are not required the loss of half of the magnitude of a Byte or Word can be significant. That is why it is necessary to be able to specify if a value is Signed or Unsigned, that is if the MSB is the sign bit or part of the value.

It is obviously important from the above that the user program ds need to know what sort of data to expect as a value of 0xFF could be considered to be both 255 and -1 depending on the interpretation of the variable.    That is why it is important to have Signed and Unsigned Data Types so that the compiler can decide how to handle or interpret the contents.   As show above in GCBASIC those types are referred to as Integer and Word respectively.

Summary

GCBASIC implements support for Bit, Byte, Word, Integer and Long Variable Types, all of which are described above.

And, that negative numbers are represented as two’s complement.  

About Variables and Variable Types

A variable is an area of memory on the microcontroller that can be used to store a number or a series of letters. This is useful for many purposes, such as taking a sensor reading and acting on it, or counting the number of times the microcontroller has performed a particular task.

Each variable must be given a name, such as "MyVariable" or "PieCounter". Choosing a name for a variable is easy - just don’t include spaces or any symbols (other than _), and make sure that the name is at least 2 characters (letters and/or numbers) long.

Variable Types

There are several different types of variable, and each type can store a different sort of information. These are the variable types that GCBASIC can currently use:

Using Variables

Byte variables do not need any special commands to set them up - just put the name of the variable in to the command where the variable is needed. However, it is good practice to "dimension" all byte variables and to use #OPTION EXPLICIT.   #OPTION EXPLICIT mandates the "dimensioning" of all variables in the user program.  Using #OPTION EXPLICIT will improve the quality of the program.

Other types of variable can be used in a very similar way, except that they must be "dimensioned" first. This involves using the DIM command, to tell GCBASIC that it is dealing with something other than a byte variable.

A key feature of variables is that it is possible the have the microcontroller check a variable, and only run a section of code if it is a given value. This can be done with the IF command.

Number Variables

You can assign values to number variables using &#160`=`.  

A simple, but typical example follows.  This is the typical for numeric variable assignment.

GCBASIC support bitwise assignments s follows:

The function FnLSL performs the shift operation found in other languages. Here is an example:

To set a bit of a port and to prevent glitches during operations, use #option volatile as folllows:

To set a bit of a port or variable, encapsulate it in the SetWith method. Using this method also eliminates any glitches during the update.

To clear a bit of a port, use this method:

To set a bit within an array, use this method:

To set a bit within a variable, use this method:

String Variables

Strings are defined as follows:

String variables default to the following rules and the RAM constraints of a specific chip.

You cannot store a string 20 characters long in a chip with 16 bytes of RAM.

You can change the default string size handled internally by the GCBASIC compiler by changing the STRINGSIZE constant:

Defining a length for the string is the best way to limit memory usage. It is good practice if you need a string of a certain size to set the length of a strings, since the default length for a string variable changes depending on the amount of memory in the microcontroller (see above).

To set the length of a string, see the example below:

To place quotation marks (" ") in a string of text. For example:

To place quotation marks (") in a string of text, use two quotation marks in a row instead of one for each quote mark. The following example shows two ways of printing She said, "You deserve a treat!". This technique works for all output methods (HSerPrint, Print, etc.)

Variable Aliases

Some variables are aliases, which are used to refer to memory locations used by other variables. These are useful for joining predefined byte variables together to form a word variable.

Aliases are not like pointers in many languages - they must always refer to the same variable or variables and cannot be changed.

When setting a register/variable bit ( i.e my_variable.my_bit_address_variable ) and using a alias for the variable then you must ensure the bytes that construct the variable are consective.

The coding approach should be to DIMension the variable (word, integer, or long) first, then create the byte aliases:

To set a series of registers that are not consecutive, it is recommended to use a mask variable then apply it to the registers:

Casting

Casting changes the type of a variable or value. To tell the compiler to perform a type conversion, put the desired type in square brackets before the variable. The following example will cause two byte variables added together to be treated as a word variable.

Why do this? Suppose that ByteVar is 150, and AnotherByteVar is 231. When added, this will come to 381 - which will overflow, leaving 125 in the result. However, when the cast is added, GCBASIC will treat ByteVar as if it were a word, and so will use the word addition code. This will cause the correct result to be calculated.

It is good practice to cast when calculating an average:

It’s also possible to cast the second value instead of the first:

The result will be exactly the same.

To apply operations to individual bits of variables see, Set, Rotate

To check variables and apply logic based on their value, see If, Do, For, Conditions

For more help, see: Declaring variables with DIM, Setting Variables

About Advanced Variable Types

A variable is an area of memory on the microcontroller that can be used to store a number or other data.   This is useful for many purposes, such as taking a sensor reading and acting on it, or counting the number of times the microcontroller has performed a particular task.

Each variable must be given a name, such as "MyVariable" or "PieCounter".   Choosing a name for a variable is easy - do not include spaces or any symbols (other than _), and make sure that the name is at least 2 characters (letters and/or numbers) long.

Advanced Types

There are a number different types of advanced variable types, and each type can store a different range of numeric information.  

With respect to advanced variables GCBASIC supports:

With respect to used advanced variables - please use Singles in your program as these have been tested. The other types are documented for completeness and should be used by developers in libraries.

Using advanced variable type maths is also much slower than integer maths when performing calculations and loops, therefore should be avoided if.   You should convert float calculations to integer maths to increase operation of your solution.   The example program (shown below) shows how use a float maths and you shuld try to do the same with integers and time the overall time for comparison.  Typically, floats are 18%-20% slower than similar integer maths operations.

The advanced variable types that GCBASIC supports are:

The format for single and double floats is defined by the IEEE 754 standard.   Sign, exponent and mantissa are all in the positions described here: https://www.geeksforgeeks.org/ieee-standard-754-floating-point-numbers/

Organisation of advanced variables

GCBASIC stores advanced variables in bytes.   The format of these bytes is:

You can access the bytes within advanced variables using the following as a guide using the suffixes _A, _B, _C etc.

Example of accessing the lowest byte, the _H, _U and the _A bytes.

Using the Byte components of Advanced Variables

This is strict. Accessing BYTE values of advanced variables requires the use cast. Failure to use cast will cause issue with the low byte ( the low byte will tranformed into a Long integer and you will provide the low byte of the Long integer).

Example. Mandated use of cast for single/float

Example assigning a HEX value to a single/float

Working example of assigning d0.5 or 0x3F000000 ( which is the IEEE574 hex value for d0.5 )

Using Advanced Variables

Advanced variables must be "DIMensioned" first.  This involves using the DIM command, to tell GCBASIC that it is dealing with an advanced variable.

Using Advanced Variables

Advanced variables are only supported by a subset of the functions of GCBASIC.  

The functional characteristics are:

Assigning Values to Advanced Variables

You can assign values to advanced variables using  `=`.  

A simple, but typical example follows.  This is the typical for numeric variable assignment.

Another example is bitwise assignments as follows:

+

INT() and SINGLRROUND()

Floating point numbers are not exact, and may yield unexpected results when compared using conditions (IF etc).   For example 6.0 / 3.0 may not equal 2.0.   Users should instead check that the absolute value of the difference between the numbers is less than some small number.

These techniques can replace the INT() and SINGLEROUND() functions.

Alternative to INT()

Assignment of a Single variable to an Interger variable is supported.  

So, use the conversion from floating point to integer as this results in integer truncation.

Alterntive tp ROUNDSSINGLE()

As an alternative to using the ROUNDSSINGLE() function.  

Create your own round conversion, add 0.5 to return the nearest integer.  As follows:

Example Program

This program shows the values of calculation of 4.5 * multiplied by a number ( 4.5 x a range of 0 to 40,000).   The program shows setting up the advanced variables, assigned a value and completing the multiplication of the initial value using a for-next loop.  

To check variables and apply logic based on their value, see If, Do, For, Conditions

For more help, see: Declaring variables with DIM, Setting Variables

This section discusses the allocation of variables to RAM ( GPR, SRAM or other TLA).

Variables in GCBASIC can be bits, bytes, words, integers, longs, arrays or reals.   This section will NOT address reals as these are developmental variables only.

Variables can also be defined as Aliases - this is discussed later in this section.

Basic variable allocation

Variables of type byte, word, integer, longs are placed in RAM using the following simple rules.

Variables of array and strings type are placed in RAM using the following simple rules.

Variables of bit type are placed in RAM using the following simple rules.

Addressing Variables

Addressing a variable memory address can be achieved by using the @ prefix.    This will return the address of the variable ( @ applies to table data and any data block).

The following example shows registers DMAnSSAU, DMAnSSAH, DMAnSSAL being loaded with the address of the array WaveArray.

AT allocation

The Dim variable command can be used to instruct GCBASIC to allocate variables at a specific memory location using the parameter AT.

The compiler will inspect the provided AT memory location and if the memory location is already used ( by an existing variable), lower than the minimum memory location or greater than the maximum memory location an error will be issued.

Variable Aliases

Variable can be defined as aliases.    Aliases are used to refer to existing memory locations SFR or RAM and aliases can be used to construct other variables.   Constructed variables can be a mix ( or not ) of SFR or RAM.    These are useful for joining predefined byte variables together to form a word/long variable.

Aliases are not like pointers in many languages - they must always refer to an existing variable or variables and cannot be changed.

When setting a register/variable bit ( i.e my_variable.my_bit_address_variable ) and using a alias for the variable then you must ensure the bytes that construct the variable are consecutive.

Aliases are shown in the ASM source in the ;ALIAS VARIABLES section.

The coding approach should be to DIMension the variable (word, integer, or long) first, then create the byte aliases:

To set a series of registers that are not consecutive, it is recommended to use a mask variable then apply it to the registers:

Memory Specification

All memory specifics like RAM size, lower and upper RAM addresses are specified in the chip specific dat file.

The dat file details should be reviewed in PICINFO application. See the PICINFO/CHIPDATA tab for RAM and MaxAddress etc.

A simple calculation is MaxAddress - RAM +1 = the 'first memory address'. And, 'first memory address' + RAM -1 = 'the last memory address.

This can be confirmed by review the DAT file. See the section [FreeRAM] for the start and end of RAM.

The dat file also has a [NoBankRAM]. NoBankRAM is somewhat misnamed - it is used for the defintion of (any) access bank locations.   If a memory location is defined in both NoBankRAM and FreeRAM, then the compiler knows that it is access bank RAM.  If an SFR location is in one of the NoBankRAM ranges, then the compiler knows not to do any bank selection when accessing that register.

The [NoBankRAM] section includes two ranges, one for access bank RAM, one for access bank SFRs. The first range MUST be the ACCESS RAM range The first range is the FAST SFR range

If there are no ranges defined in NoBankRAM, the compiler will try to guess them.   On 18Fs, it will guess based on where the lowest SFR is, and from what the total RAM on the chip is.   If there’s only one range defined.    in the NoBankRAM locations, the compiler will assume that is the range for the RAM, and then will guess where the range for the access bank SFRs is.

In the example shown above the following can be extracted.

Introduction

This section explores the efficient implementation of lookup reference tables in embedded systems, specificially GCBASIC, focusing on the use of PROGMEM memory to store fixed data sets. It addresses common misconceptions about data storage and initialization, compares different methods of data handling, and provides advanced techniques for optimizing memory usage.

Lookup reference tables are essential in embedded systems for storing fixed data sets that can be accessed during runtime. This section aims to clarify the correct implementation of these tables, debunking common myths and providing practical solutions for efficient data management.

Conventional Misconceptions

A common misconception is that the data required by a fixed lookup table is defined by its content and declared in a Dim statement, with its data filled at runtime. This implies that an array ( in RAM memory ) is empty initially and populated during initialization, leading to data duplication and wasted memory resources.

Correct Implementation

A fixed lookup table is a set of data (bytes, words, etc.) stored in the PROGMEM memory. The correct implementation involves using the TABLE and READTABLE commands: * Definition: TABLE tablename…​ data…​ END TABLE * Reading: READTABLE There is no DIM in the definition process, and the data is part of the hex file, not filled at runtime.

Memory Efficiency

Storing data in PROGMEM ensures that there is only one copy of the data, avoiding duplication. Copying data to an array is redundant as reading the table can replace the array.

Practical Solutions

Using TABLE - END TABLE is the simplest way to handle data. For data sets smaller than the EEPROM in the chip, load the table directly to EEPROM and use READTABLE to read the data.

Advanced Techniques

Arrays in Embedded Systems

An array is a special type of variable that can store multiple values, addressed individually using an index. Arrays can be bytes, longs, integers, or words, and are held in RAM. Loading an array can be done element by element or all at once.

Comparison of Methods

Using arrays can be costly in terms of RAM and PROGMEM. The following examples illustrate the difference:

Using an Array

64 words Progmem / 13 bytes RAM

Using a Table

56 words Progmem / 2 bytes RAM

Usage

The ReadTable method provides data set capabilities to chips with limited RAM, using fewer resources and offering faster performance. Advanced techniques and proper understanding of memory usage can significantly optimize embedded system performance.

Notes

By following these guidelines, developers can efficiently implement lookup reference tables in embedded systems, optimizing memory usage and performance.

About Arrays

An array is a special type of variable - one which can store several values at once.  It is essentially a list of numbers in which each one can be addressed individually through the use of an "index".

The numbers can be bytes (the default), longs, integers, or words.   The index is a value in brackets immediately after the name of the array.

All the numbers stored in an array must be of the same type.   For instance, you cannot store bytes and words in the same array.

Array are are 1-based.   The first element is element zero.

Examples of array names are:

Defining an array

Use the DIM command to define an array.

The number of elements can be number or a constant - not a variable.

The value for the number elements in an array must be a number or constant. The compiler allocates RAM for arrays at compile time, and therefore you cannot use a variable because during compilation the value of a variable cannot be determined.

Assigning values to an array

It is possible to set several elements of a byte array with a single line of code. This short example shows how:

When using this method above element 0 of the array TestVar will be set to the number of items in the list, which in this case is 9.   Each element of the array will then be loaded with the corresponding value in the list - so in the example, TestVar(1) will be set to 1, TestVar(2) to 2, and so on.   Element 0 will only be set to number of items in the array when using this method.   For microcontrollers with less than 2048 bytes of RAM the limit is 250 elements or the array cannot exceed the microcontrollers RAM size.   For microcontrollers with more than 2048 bytes of RAM the limit is 255 elements.

This only works for byte arrays, however. For arrays of type integer, word, or long, each element must be set separately:

If each element has the same value, this can be shortened using a loop:

Array Length

Element 0 should not be used to obtain the length of the array.   Element 0 will only be a consistent with respect to the length of the array when the array is set as shown above.

The correct method is to use a constant to set the array size and use the constant within your code to obtain the array length.

Using Arrays

To use an array, its name is specified, then the index. Arrays can be used everywhere that a normal variable can be used.

Maximum Array Size

The limit on the array size is dependent on the chip type, the amount of RAM, and the number of other variable you use in your program.

Use the following simple program to determine the maximum array size. Set CHIP to your device, MAXSCOPE to a value which is less the total RAM, and the data type of test_array to the data type to be stored in the array.

The data type of imaxscope must be set to match the size of the constant MAXSCOPE. If MAXSCOPE ⇐ 255, imaxscope should be a byte.   If MAXSCOPE > 255, imaxscope should be a word.

If the array is too large to fit, the compiler will issue an error message.   Reduce MAXSCOPE until the error message is not issued.   The largest MAXSCOPE value without an error message is the largest useable array of this type for this chip.

For the Atmel AVR, LGT 328p or an 18F array sizes are limited to 10,000 elements.

If a memory limit is reached, the compiler will issue an error message.

Get the most from the available memory

Array RAM usage is determined by the architecture of the chip type.   Getting most out of the available memory is determined by the allocation of the array within the available banks of memory.

An example is an array of 6 or 7 bytes when there is only 24 bytes of RAM and the 24 bytes is split across multiple memory banks.   Assume in this example that 18 bytes have allocated to other variables and there is 29 bytes total available.   An array of 6 bytes will fit into the free space in one bank, but the array of 7 will not.

GCBASIC currently cannot split an array over banks, so if there are 6 bytes free in one bank and 5 in another, you cannot have an array of 7 bytes.    This would be very hard to do efficiently on 12F/16F as there would be a series of special function registers in the middle of the array when using a 12F or 16F.   This constraint is not the case on 16F1/18F as linear addressing makes it easy to span banks because the SFRs are not making the problem (as with 12F/16F).

Using Tables as an alternative.

If there are many items in the array, it may be better to use a Lookup Table to store the items, and then copy some of the data items into a smaller array as needed.

For more help, see Declaring arrays with DIM,Declaring memory with ALLOC

About Comments

Adding comments to your GCBASIC program can be done using a number of methods.    Explanatory notes embedded within the code.   Comments are used to remind yourself and to inform others about the function of your program.   Comments are ignored by the compiler

You can comment out sections of code if you want just by placing an apostrophe at the beginning of each line. The GCBASIC IDE has a feature to do this automatically.

You can also use a REM (for REMark statement), a semi-colon or two forward slashes.

Multiline comments are support for large text descriptions of code or to comment out chunks of code while debugging applications.

Syntax:

Warning: Graphical GCBASIC uses semi-colons to mark comments that it has inserted automatically. It does not read these comments when opening a file, so any comments in a GCBASIC program starting with a semi-colon will be deleted if the program is opened using Graphical GCBASIC.

Example:

About Line Continuation

A single _ (underscore) character at the end of a line of code tells the compiler that the line continues in the next line. This allows a single statement (line of code) to be spread across multiple lines in the input file, which can provide nice formatting.

Be careful when adding the _ line continuation character right behind an identifier or keyword. It MUST be separated with at least one space character, otherwise it would be treated as part of the identifier or keyword.

Example 1:

This example will print on the serial terminal the string "one two three four five six seven eight nine ten eleven twelve thirteen fourteen fifteen sixteen seventeen eighteen nineteen twenty twentyOne twentyTwo twentyThree twentyFour twentyFive"

Example 2:

This example improves the layout of definition of the sub-routine.

Example 3:

This example creates a constants over two lines. This improves readability.

About Conditions

In GCBASIC (and most other programming languages) a condition is a statement that can be either true or false. Conditions are used when the program must make a decision. A condition is generally given as a value or variable, a relative operator (such as = or >), and another value or variable. Several conditions can be combined to form one condition through the use of logical operators such as AND and OR.

GCBASIC supports these relative operators:

In addition, these logical operators can be used to combine several conditions into one:

NOT is slightly different to the other logical operators, in that it only needs one other condition. Other arithmetic operators may be combined in conditions, to change values before they are compared, for example.

GCBASIC has two built in conditions - TRUE, which is always true, and FALSE, which is always false. These can be used to create Conditional tests and infinite loops.

The condition bit_variable = TRUE is treated as TRUE if the bit is on.  Any non-zero value will be treated as equal to a high bit. The condition bit_variable = other_type_of_variable generates a warning.  If the byte_variable is set to TRUE and then compared to the bit, it will always be FALSE because the high bit will be treated as a 1.  But the new warning will be generated, "Comparison will fail if %nonbit% is any value other than 0 or 1"

It is also possible to test individual bits in conditions. To do this, specify the bit to test, then 1 or 0 (or ON and OFF respectively). Presently there is no way to combine bit tests with other conditions - NOT, AND, OR and XOR will not work.

Example conditions:

Constraints when using Conditional Test

As GCBASIC is very flexible with the use of variables type this can cause issues when testing constants and/or functions.

A few simple rules. Always put the function or constant first, or, always call the function with the addition of the braces.

The example code below shows the correct method and an example that does compile but will not work as expected.

This fails as the function will not be called

About Constants

A constant tells the compiler to find a given string, and replace it with another string. The #Define directive create constants.

Constants are useful for situations where a routine needs to be easily altered. For example, a define could be used to specify the amount of time to run an alarm for once triggered.

It is also possible to use defines to specify port.pin(s) - thus defines can be used to aid in the creation of code that can easily be adapted to run on a different microcontroller with different ports.

GCBASIC makes considerable use of defines internally. For instance, the LCD code uses defines to set the ports that it must use to communicate with the LCD.

About Defines

To create a constant is a matter of using the #define directive. Here are some examples of defines:

LINE is a simple constant - GCBASIC will find LINE in the program, and replace it with the number 34. This could be used in a line following program, to make it easier to calibrate the program for different lighting conditions.

LIGHT is a port.pin - it represents a particular pin on the microcontroller. This would be of use if the program had many lines of code that controlled the light, and there was a possibility that the port the light was attached to would need to change in the future.

LIGHTON is a define used to make the program more readable. Rather than typing Set PORTB.0 ON over and over, it would then be made possible to type LIGHTON, and have the compiler do the hard work.

GCBASIC Defined constants

The are many GCBASIC standard constants, some are show below.

A GCBASIC special constant

FOREVER is a special constant. For Graphical GCBASIC users think of this as 'false'. For those not using Graphical GCBASIC think of this as a non numeric value that has no value. You can use FOREVER in a DO-LOOP but not in a REPEAT-END REPEAT loop, as the in the later case the REPEAT will have no value and you will create an error condition.

Precedence of Constants within GCBASIC.

The #define command creates constants, and, scripts also creates constants. See the #script section of ths Help.

The precedence is as follows:

All constants are listed in the Constant Debug File ( CDF ). The CDF shows all constants and the end state of the constants.

See #define

About Functions

Functions are a special type of subroutine that can return a value.   This means that when the name of the function is used in the place of a variable, GCBASIC will call the function, get a value from it, and then put the value into the line of code in the place of the variable.

Functions are strict.  The function MUST be assigned to an appropiate variable or passed to another subroutine.  Calling a function with no assignment or returned value usage will raise an error condition.

Functions may have parameters - these are treated in exactly the same way as parameters for subroutines.   The only exception is that brackets are required around any parameters when calling a function.   The argument’s type is given by "As type" following the parameter. If a parameter in the declaration is given a default value, the parameter is optional. Array parameters are specified by following an identifier with an empty parenthesis.

Returning values : return_type specifies the data type returned by a function upon exit.  If no data type is specified, then the function will return the default data type which is a byte.   Functions return values by assigning the Function keyword or the function’s identifier to the desired return value, this method do not cause the function to exit, however.  

Exit Function keyword in a same function is unsupported when returning objects with constructors.  Since functions return values, function calls evaluate to expressions. Thus, function calls can be made wherever an expression is expected, like in Assignments or If statements.  Parentheses surrounding the argument list are required on function calls in expressions and even highly recommended if there are no arguments.

Using Functions

This program uses a function called AverageAD to take two analog readings, and then make a decision based on the average:

See Also Subroutines, Exit

About Labels

Labels are used as markers throughout the program. Labels are used to mark a position in the program to ‘jump to’ from another position using a goto, gosub or other command.

Labels can be any word (that is not already a reserved keyword) and may contain digits and the underscore character. Labels must start with a letter or underscore (not digit), and are followed directly by a colon (:) at the marker position. The colon is not required within the actual commands.

The compiler is not case sensitive. Lower and/or upper case may be used at any time.

Example:

For more help, see Goto, Gosub

About Lookup Tables

A lookup table is a list of values that are stored in the memory of the microcontroller, which then can be accessed using the ReadTable command.

The advantage of lookup tables is that they are memory efficient, compared to an equivalent set of alternative command statements.

Data tables are defined as follows:

Defining Tables

Single data values

A single value on each line with in the table.  The example table, shown below, has the data on different line in within the table.

Multiple data values of the same line

Multiple elements on a single line separated by commas.  The example table, shown below, has the data separated by , and on different line in within the table.

Data values as constants, and, with data transformation

Constants and calculations within the single line.   The example table, shown below, uses a defined constant to multiple the data with the table.

Data values as Strings

Strings can be defined.  Strings are delimited by double quotes.    The following examples show the methods.

Any ASCII characters between any two " " (double quotes) will be converted to table data.   Also see ASCII escape codes.

A source string can be one string per line or comma separated strings, therefore, on the same line.

Simple Example 1.

Simple Example 2.

The following 2 table lines produce the same table data.

And, the following 3 table lines produce the same table data.

ASCII Escape code

Accepted escape strings are shown in the table below.

Using Lookup Tables

First, the table must be created. The code to create a lookup table is simple - a line that has Table and then the name of the table, a list of numbers (up to 10,000 elements), and then End Table.

For tables with more than 255 elements it is mandated to used a WORD variable to read the size of the table. See below for an example.

Once the table is created, the ReadTable command is used to read data from it. The ReadTable command requires the name of the table it is to read, the location of the item to retrieve, and a variable to store the retrieved number in.

Lookup tables can store byte, word, longs and integer values.   GCBASIC will try automatically detect the type of the table depending on the values in it.   GCBASIC can be explicitly instructed to cast the table to a variable type, as follows:

Addresssing the Table Data

Item 0 of a lookup table stores the size of the table. If the ReadTable command attempts to read beyond the end (number of data items) of the table, the value 0 will be returned. For tables with more than 255 elements it is mandatory to use a WORD variable to read the size of the table. See example below.

Importing External Text File for table conversion

An external file can be used as the table data source.   The file will be read into the specified table name from the external file.   The source file will be treated as a byte value file.

An example file is shown below:

The following program will import the external data file.

And the program will out the following:

Advanced use of Lookup Tables - using EEPROM for Table data storage

You can use the Table statement to store the data table in EEPROM. If the compiler is told to store a data table in "Data" memory, it will store it in the EEPROM.

NOTE The limitation of of using EPPROM tables is that you can only store BYTEs. You cannot store WORD values in the EEPROM tables.

Example code:

For more help, see ReadTable

About Miscellaneous things…​.

It is possible to combine multiple instructions on a single line, by separating them with a colon. For example, this code:

could also be written as:

In most cases, it will make no difference if commands share a line or not. However, special care should be taken with If commands, as this code:

Will be equivalent to this:

Also, the commands used to start and end subroutines, data tables and functions must be alone on a line. For example, this is WRONG:

About ReadTable

The ReadTable command is used to read information from lookup tables. TableName is the name of the table that is to be read, Item is the line of the table to read, and Output is the variable to write the retrieved value in to.

Syntax:

Command Availability:

Available on all microcontrollers.

Explanation:

Item is 1 for the first line of the table, 2 for the second, and so on. If the Table is more than 256 elements then Item must be WORD variable. Care must be taken to ensure that the program is not instructed to read beyond the end of the table as Zero will be returned.

The type of Output should match the type of data stored in the table. For example, if the table contains Word values then Output should be a Word variable. If the type does not match, GCBASIC will attempt to convert the value.

Example:

For more help, see Lookup Tables

About Scripts

A script is a small section of code that GCBASIC runs when it starts to compile a program. Uses include performing calculations that are required to adjust the program for different chip frequencies.

Scripts are not compiled or downloaded to the microcontroller - GCBASIC reads them, executes them, then removes them from the program and then the results calculated can be used as constants in the user program.

Inside a script, constants are treated like variables. Scripts can read the values of constants, and set them to contain new values.

Using Scripts

Scripts start with #script and end with #endscript. Inside, they can consist of the following commands:

If is similar to the If command in normal GCBASIC code, except that it does not have an Else clause. It is used to compare the values of the script constants.

The = sign is identical to that in GCBASIC programs. The constant that is to be set goes on the left side of the = and the new value goes to the right of the =.

Error is used to display an error message. Anything after the Error command is displayed at the end of compilation, and is saved in the error log for the program.

Warning is used to display a warning message. Anything after the Warning command is displayed at the end of compilation but warning does not halt compilation.

Int() will calculate the integer value of a calculation. Using Int() is critical to set the constant to the integer component of the calculation.

Notes:

Use Warning to display constant values when creating and debugging scripts.

Scripts have a limited syntax and limited error checking when compiling. The compiler may halt if you get something wrong.

Scripts that are incorrectly formatted may also halt the compiler or return unrelated error.

Scripts used for calculations should use the Int( expression ) where you may have a floating point numbers returned.
Scripts do use floating point for all calculations and a failure to use Int() may set the script constant and the resulting constant to 0.

Scripts may require that complex math expressions may require definition in multiple steps/line to simplify the calculation.
The returned value could be incorrect if simplification is not implemented.

Scripts can only access existing constants both user and system defined.

User defines variables are not accessible within the scope of a script.

Scripts has precendence over #define. A #define constant statements are read first, then scripts run. So, a script will always overwrite a constant that was set with #define.

Use Warning to display constants values when creating and debugging scripts.

Example Script

This script is used in the pwm.h file. It takes the values of the user defined constants PWM_Freq, PWM_Duty and system constant ChipMHz and calculates the results using the equations. These calculation are based on information from a Microchip PIC datasheet to calculate the correct values to setup Pulse Width Modulation (PWM).

During the execution of the script the calculations and assignment uses the constants in the script.

After this script has completed the constants PR2Temp, DutyCycleH and DutyCycleL are set using the constants and/or the calculations.

The constants assigned in this script, PR2Temp, DutyCycleH and DutyCycleL, are made available as constants in the user program.

About Subroutines

A subroutine is a small program inside of the main program. Subroutines are typically used when a task needs to be repeated several times in different parts of the main program.

There are two main uses for subroutines:

When the microcontroller comes to a subroutine it saves its location in the current program before jumping to the start of, or calling, the subroutine. Once it reaches the end of the subroutine it returns to the main program, and continues to run the code where it left off previously.

Normally, it is possible for subroutines to call other subroutines. There are limits to the number of times that a subroutine can call another sub, which vary from chip to chip:

These limits are due to the amount of memory on the microcontroller which saves its location before it jumps to a new subroutine. Some GCBASIC commands are subroutines, so you should always allow for 2 or 3 subroutine calls more than your program has.

On 16F chips, the program memory is divided into pages. Each page holds 2048 instructions.    If the program jumps from code on one page to code on another, the compiler has to select the new page.   Having to do this makes the program bigger, so try to avoid this. To keep jumps between pages down, GCBASIC imposes a rule that each subroutine must be entirely within one page, so that only jumps to other subroutines require the page selection.    As an example, say you have two pages of memory, each 2048 instructions (words) long.
If you have a main sub that is 1500 words, and four other subroutines each 600 words long, your total program size would be 3900 words and you might expect it to fit into the 4096 words available.     The problem though is that once the main routine takes 1500 words from page 1, nothing else will fit after it. Three of the 600 word subroutines would fit onto page 2, but that leaves one 600 word subroutine that will not fit into the 500 left on page 1 or the 200 left on page 2.    If you want to reduce the chance of this happening, the best option is to keep your subroutines smaller - move anything out of the main routine and into another one - this will resolve memory page constraints.   

Atmel AVR microcontrollers have no fixed limit on how many subroutines can be called at a time, but if too many are called then some variables on the chip may be corrupted. To check if there are too many subroutines, work out the most that will be called at once, then multiply that number by 2 and create an array of that size. If an out of memory error message comes up, there are too many calls.

Another feature of subroutines is that they are able to accept parameters. These are values that are passed from the main program to the subroutine when it is called, and then passed back when the subroutine ends.

Using Subroutines

To call a subroutine is very simple - all that is needed is the name of the sub, and then a list of parameters. This code will call a subroutine named "Buzz" that has no parameters:

If the sub has parameters, then they should be listed after the name of the subroutine. This would be the command to call a subroutine named "MoveArm" that has three parameters:

Or, you may choose to put brackets around the parameters, like so:

All that this does is change the appearance of the code - it doesn’t make any difference to what the code does. Decide which one meets your own personal preference, and then stick with it.

Creating subroutines

To create a subroutine is almost as simple as using one. There must be a line at the start which has sub, and then the name of the subroutine. Also, there needs to be a line at the end of the subroutine which reads end sub. To create a subroutine called Buzz, this is the required code:

If the subroutine has parameters, then they need to be listed after the name. For example, to define the MoveArm sub used above, use this code:

In the above sub, ArmX, ArmY and ArmZ are all variables. If the call from above is used, the variables will have these values at the start of the subroutine:

When the subroutine has finished running, GCBASIC will copy the values back where possible. NewX will be assigned to ArmX, and NewY will be assigned to ArmY. GCBASIC will not attempt to set the number 10 to ArmZ.

Controlling the direction data moves in

It is possible to instruct GCBASIC not to copy the value back after the subroutine is called. If a subroutine is defined like this:

Then GCBASIC will copy the values to the subroutine, but will not copy them back.

GCBASIC can also be prevented from copying the values back, by adding Out before the parameter name. This is used in the EEPROM reading routines - there is no point copying a data value into the read subroutine, so Out has been used to avoid wasting time and memory. The EPRead routine is defined as Sub EPRead(In Address, Out Data).

Many older sections of code use #NR at the end of the line where the parameters are specified. The #NR means "No Return", and when used has the same effect as adding In before every parameter. Use of #NR is not recommended, as it does not give the same level of control.

Using different data types for parameters

It is possible to use any type of variable a as parameter for a subroutine. Just add As and then the data type to the end of the parameter name. For example, to make all of the parameters for the MoveArm subroutine word variables, use this code:

Optional parameters

Sometimes, the same value may be used over and over again for a parameter, except in a particular case. If this occurs, a default value may be specified for the parameter, and then a value for that parameter only needs to be given in a call if it is different to the default.

For example, suppose a subroutine to create an error beep is required. Normally it emits ! 440 Hz tone, but sometimes a different tone is required. To create the sub, this code would be use:

Note the Optional before the parameter, and the = 440 after it. This tells GCBASIC that if no parameter is supplied, then set the OutTone parameter to 440.

If called using this line:

then a 440 Hz beep will be emitted. If called using this line:

then the sub will produce a 1000 Hz tone.

When using several parameters, it is possible to make any number of them optional. If the optional parameter/s are at the end of the call, then no value needs to be specified. If they are at the start or in the middle, then you must insert commas to allow GCBASIC to tell where the optional parameters are.

Overloading

It is possible to have 2 subroutines with the same name, but different parameters. This is known as overloading, and GCBASIC will automatically select the most appropriate subroutine for each call.

An example of this is the Print routine in the LCD routines. There are actually several Print subroutines; for example, one has a byte parameter, one a word parameter, and one a string parameter. If this command is used:

Then the Print (byte) subroutine will be called. However, if this command is used:

Then the Print (word) subroutine will be called. If there is no exact match for a particular call, GCBASIC will use the option that requires the least conversion of variable types. For example, if this command is used:

The byte print will be used. This is because byte is the closest type to the single bit parameter.

See Also Functions, Exit

About Converters

Converters allow GCBASIC to read files that have been created by other programs. A converter can convert these files into GCBASIC libraries or any GCBASIC instruction or a GCBASIC dataset.

A typical use case is when you have a data source file from another computer system and you want to consume the data within your GCBASIC program. The data source file could be database, graphic, reference data or music file. The converter will read these source files and convert them into a format that can be processed by GCBASIC. The conversion process is completed by external application which can be written by the developer or you can use one of the converters provided with the GCBASIC release.

The GCBASIC release includes the converter for BMP files and standard Text files.

With an appropriate Converter installed, and an associated #include to these non-GCBASIC files, GCBASIC will detect that the file extension and hand the processing to the external converting program. When the external converting program had complete, GCBASIC will then continue with the converted source file as a GCBASIC source file.

An example of a converter is to read an existing picture file, convert the picture file to a GCB table and then refer to the picture file table to display the picture file on a GLCD.

Conversion is achieved by including a command within the source program to transform external data. The command used is the instruction #include followed by the data source. An example:

The inclusion of the #include line within a GCBASIC program will enable the commencement of the following process:

For example programs see here.

More about Converters

Example 3 : Converter Program

Example 4 : Dynamic Import

Example 5 : Add build numbers and time/date details to your programs

This converter is used to expose two string variables as follows:

The user code is simple. Using the #include statement specify any filename with an extension must be cnt. As follows:

Complete code would like this - this not optimised - this shows the use of the exposed strings.

This outputs the following - where #20 is the current build and the date/time is correct for build time.

This works as the support INI file instructs the compiler to call a utility that automatically creates a build number tracker file and the supportting string functions. The utility creates a tracker file and the methods files in the same folder as your source program - so, each tracker is specific to each project. The converter requires the following files - these are included within your Installation.

This is the Analog/Digital conversion section of the Help file. Please refer the sub-sections for details using the contents/folder view.

This is the Bitwise section of the Help file. Please refer the sub-sections for details using the contents/folder view.

This is the Memory section of the Help file. Please refer the sub-sections for details using the contents/folder view.