Interactive Tutorial

The xSOFTip Explorer has five windows:

• xSOFTip Browser: shows the xSOFTip components you can chose for your project
• My System Configuration: the xSOFTip components you have selected
• My System Information: the resources used by the xSOFTip components you have selected, and the XMOS multicore microcontrollers which suit your application
• Next Steps: information and activities we recommend you try next
• Developer Column: online documentation about the xSOFTip, tools and xCORE multicore microcontrollers. The Developer Column can have multiple tabs. While running this tutorial, you can swap to the Main tab to view the documentation for the xSOFTip components.

Choose some xSOFTip for your first application.

1. Select the Ethernet/TCP xSOFTip from the Networking>Ethernet category.

   The Developer Column shows information about this component, including a description of what it does, its features and which xKIT development kits are suitable for use with this xSOFTip. You will need to switch to the Main tab at the bottom of the Developer Column to view the xSOFTip documentation. You can switch back to this tutorial by clicking the xTutorial tab.

2. Drag the Ethernet/TCP xSOFTip into the My System Configuration window.
3. Click on the arrow on the left of the Ethernet/TCP module to view the configuration for the component.
4. Select the Ethernet/TCP Module in the My System Configuration window. The Main tab of the Developer Column provides a description of each configuration option.

As all peripherals in XMOS are implemented using software, you have complete freedom to customise the interface to meet your exact requirements. In this example you will be using the default configuration, so no changes are needed.

The My System Information window shows the resources used by your configuration. As you add components, the window is updated to show the resources used by all the selected xSOFTip components.

Resources include:

• Logical Cores: 32bit microcontroller cores. XMOS multicore microcontrollers include 4, 6, 8, 10, 12, 16 and 32 core devices.
• Ports: I/O pins of XMOS multicore microcontrollers are connected to ports, which allow your software to send and receive data to the pins with extremely low latency. Ports are available in different widths: a 1-bit port is connected to 1 I/O pins, a 4-bit port is connected to 4 I/O pins.
• Clock Blocks: Clock blocks are used to precisely control timing of I/O pins.
• Chanends: Channel Ends are part of the xConnect system, allowing the cores to send messages to each other through low latency xConnect channels.
• Timers: Timers are used by the software to control the time at which things happen. They run at 100MHz, giving 10ns precision.

All XMOS I/O pins are general purpose, so you can use them for any hardware interface you need.

Select the following xSOFTip components to provide the interfaces you need in our system. Drag them into the My System Configuration window:

1. Select the I2S Master Audio Driver in the Audio/Interfaces category (or use the Search box to find it).

   This will be used to send and receive audio data.

2. Select the SDRAM Memory Controller interface in the Memory/Volatile category.

   An external SDRAM will provide a large external memory that you can use to store audio data for the Reverb effect.

3. Select the Long Reverb Function Library in the Audio/DSP category.

   Use the Reverb library to implement reverb.

4. Select the I2C Master (Single Bit Ports) Function Library in the Peripherals/Serial category.

   The I2C interface will be used to control external devices.

Making changes to your XMOS design is very easy. Perhaps you now need a UART interface rather than I2C.

1. Right-click on the I2C Master (Single Bit Ports) Function Library and click Delete.
2. Select the Generic UART Transmitter (Peripherals/Serial) in the xSOFTip Browser and drag it into the My System Configuration window.

Take a look at the other xSOFTip components and add anything else you want in your system.

XMOS and our partners are working on new xSOFTip components all the time. Some components you see here are roadmap components which are in our development plan. If there is a component you require for your system, please let us know – we’d love to hear from you.

Each xSOFTip component is categorized with a Scope, which shows the status of the xSOFTip component:

• General Use: The xSOFTip consists of a complete release from XMOS.

  Complete resource information is available.

  NOTE: All attempts have been made to ensure the correct functionality of this block, but the
  final quality of any product using this block is the responsibility of the user.

• Early Development: The xSOFTip is suitable for use in development of products and is fully functional.
  However, the maturity of the software is such that extra care must be taken in verifying a product
  using this software block. Resource information is available.
• Experimental: The xSOFTip is at an experimental/prototype stage. Code exists but is not feature complete.
  Resource information may be available.
• Roadmap: The xSOFTip is on the XMOS development roadmap. Estimated resource information exists
  for this xSOFTip, but no code is available.
• Open Source Community: The xSOFTip has been developed by the Open Source community.
  Resource information may not be available.

You can add xSOFTip components directly to your application using the xSOFTip Explorer perspective.

1. Click on the Tutorial Example LED PWM Driver xSOFTip component in the sliceKIT/demos category.

   The Developer Column shows information on the component including a description of what it does,
   its features and which xKIT Development Kits are suitable for use with this xSOFTip.

2. Drag the Tutorial Example LED PWM Driver xSOFTip into the My System Configuration window.

   All peripherals in XMOS are implemented using software, giving you complete freedom to
   customize the interface to meet your exact requirements.

   xSOFTip is all delivered as C code, so you easily change it to meet your exact requirements.
   You can also take existing C functions and run them on an xCORE. For interfacing to I/O pins
   and for communicating between logical cores, XMOS has added a handful of operations to C, called ‘XC’.

3. The My System Information window is updated to show the resources used by your system configuration.

   Resources include:

   • Logical Cores: 32bit microcontroller cores. XMOS multicore microcontrollers include 4, 6, 8, 10, 12, 16 and 32 core devices.
   • Ports: I/O pins of XMOS multicore microcontrollers are connected to ports, which allow your software to send and receive data to the pins with extremely low latency. Ports are available in different widths: a 1-bit port is connected to 1 I/O pins, a 4-bit port is connected to 4 I/O pins.
   • Clock Blocks: Clock blocks are used to precisely control timing of I/O pins.
   • Chanends: Channel Ends are part of the xConnect system, allowing the logical cores to send messages to each other through low latency xConnect channels.
   • Timers: Timers are used by the software to control the time at which things happen. They run at 100MHz, giving 10ns precision.

A list of Possible Devices is displayed at the bottom of the My System Information window. This shows the xCORE multicore microcontrollers that most are suitable for this application.

Take a look at our xKITS at http://1m2n3b4v.xmos.com/discover/products/xkits
.

If you’re not sure which to choose, we recommend our sliceKIT Starter Kit
.

If you have a sliceKIT starter Kit we recommend that you follow the sliceKIT Development Board Tutorial, which shows you how to run the project you created in this tutorial on a hardware board. It also shows you how to use the real-time features of xCORE multicore microcontrollers to extend the PWM application to create a temperature controlled LED dimmer.

See Help > Tutorials > sliceKIT Development Board Tutorial.

Take a look at the other xSOFTip components. You can read through the documentation
in Developer Column, and use them in your project.

XMOS and our partners are working on new xSOFTip components all the time. Some
components you’ll see are Roadmap components which are in our development plan.
If there is a component you require for your system that is not available, please
let us know – we’d love to hear from you.

We provide a range of tutorials covering the xTIMEcomposer tools, xSOFTip and
xKIT development boards. See Help > Tutorials for more information.

Before writing any code, you need a project to store your files in. To create a new project follow these steps:

1. Choose FileNewXDE Project () to open the New XDE Project dialog.

   Alternatively, click here to automate steps 1, 3 and 4.

2. In Project Name, enter a name such as illuminate.
3. In Target Hardware, select the option XK-1A Development Board.
4. In Application Sofware, select the option Empty XC File.
5. Click Finish.

   The XDE creates a new project, then adds an empty source file to the project and opens it in the editor.

   

The program below illuminates an LED on an XK-1A.

#include <xs1.h>

out port led = XS1_PORT_4F;

int main () {
  led <: 0b0001;
  while (1)
    ;
  return 0;
}

Copy and paste the code into your project, and then choose FileSave () to save your changes to file.

Take a look at the code in the editor. The declaration

out port led = XS1_PORT_4F;

declares an output port named led, which refers to the 4-bit port 4F. On the XK-1A, the I/O pins of
port 4F are connected to the LEDs labeled LED0, LED1, LED2 and LED3.

Show image of port map…

XC input and output statements make it easy to express I/O operations on ports.
The statement

led <: 0b0001;

causes the value specified to the right of <: to be output to the port specified
to its left (led). The port then drives LED0 high and the other LEDs low,
causing LED0 to illuminate yellow and the other LEDs to remain off.

The empty while loop prevents the program from terminating,
which ensures that the LED remains illuminated.

To build and run your project, follow these steps:

1. In the Project Explorer, click your project to select it, and then choose the menu option ProjectBuild Project ().

   The XDE displays its progress in the Console. When the build is complete,
   the XDE adds the compiled binary file to the subfolder
   bin/Debug.

   

2. Choose RunRun Configurations.
3. In the Run Configurations dialog, in the left panel, double-click XCore Application.
4. In the right panel, in Name, enter the name illuminate.
5. In Project, ensure that your project is displayed. If not,
   click Browse to open the Project Selection dialog, select your project, and then click OK.
6. In C/C++ Application, click Search Project to open the Program Selection dialog,
   select your application binary, and then click OK.
7. In Device options, in Run on, select the option hardware, and
   in Target, ensure that the option “XMOS XTAG-2 connected to L1[0]” is
   selected.

   If your hardware is not displayed, ensure that your XK-1A is
   connected to your PC, and then click Refresh list.

8. Click Run to save your configuration and run it.

   The XDE loads the binary onto your XK-1A, displaying its progress in
   the Console. When the binary is loaded, the Console is cleared.

9. On your XK-1A, verify that LED0 is illuminated yellow.
10. In the Console, click the Terminate button () to
    stop your application running.

To complete this part of the tutorial, perform the following steps:

1. Modify your application so that it illuminates all four LEDs.

   Show a tip…

   You should change the value output to the port led so that all four LEDs are driven high.

   Show a sample answer…

   #include <xs1.h>
   
   out port led = XS1_PORT_4F;
   
   int main () {
     led <: 0b1111;
     while (1)
       ;
     return 0;
   }
   

2. Click the Run button () to reload your last Run Configuration.

   The XDE determines that your source code has been updated and re-builds it,
   displaying progress in the Console.

   If your application contains errors, the XDE displays a dialog asking if you want to
   continue launching the application. Click No, locate the first error in the
   Console and double-click it to go to the offending line in the editor. When
   you have fixed all errors, re-run your application.

3. On your XK-1A, verify that all four LEDs are illuminated, and then click the
   Terminate button () to stop your application running.

The program below flashes a single LED on an XK-1A.

#include <xs1.h>

#define FLASH_PERIOD 20000000

out port led = XS1_PORT_4F;

int main (void) {
  timer tmr;
  unsigned isOn = 1;
  unsigned t;
  tmr :> t;
  while (1) {
    led <: isOn;
    t += FLASH_PERIOD;
    tmr when timerafter (t) :> void;
    isOn = !isOn;
  }
  return 0;
}

Copy and paste the code into your project, and then choose FileSave () to save your changes to file.

Take a look at the code in the editor. The declaration

timer tmr;

declares a variable named tmr, and allocates an available hardware timer. The
L1 provides 10 timers, which can be used to determine when an event happens, or to
delay execution until a particular time. Each timer contains a 32-bit
counter that is incremented at 100MHz and whose value can be input at any time.

The statement

tmr :> t;

inputs the value of tmr‘s counter into the variable t. Having recorded the
current time, the statement

t += FLASH_PERIOD;

increments this value by the required delay, and the statement

tmr when timerafter(t) :> void;

delays inputting a value until the specified time is reached. The input
value is not needed, which is expressed as an input to void.

To build and run your project, follow these steps:

1. In the Project Explorer, click your project to select it, and then choose the menu option ProjectBuild Project ().

   The XDE builds your project, displaying its progress in the Console.
   When the build is complete, the XDE adds the compiled binary file to the application subfolder bin/Debug.

2. Create a new Run Configuration for your application named flash, and run it.

   Show reminder…

   Follow these steps:

   1. Choose RunRun Configurations.
   2. In the Run Configurations dialog, in the left panel, double-click XCore Application.
   3. In the right panel, in Name, enter the name flash.
   4. In Project, ensure that your project is displayed. If not,
      click Browse to open the Project Selection dialog, select your project, and then click OK.
   5. As there are now two applications in your project, the XDE is unable to select one automatically.
      To select, in C/C++ Application, click Search Project to open the Program Selection dialog, select your
      application binary, and then click OK.
   6. In Device options, in Run on, select the option hardware, and
      in Target, ensure that the option “XMOS XTAG-2 connected to L1[0]” is
      selected.

      If you did not stop your previous application running, your hardware
      may be displayed as “XMOS XTAG-2 connected to None”.

   7. Click Run to save your configuration and run it.

      The XDE loads the binary onto your XK-1A, displaying its progress in
      the Console. When the binary is loaded, the Console is cleared.

3. On your XK-1A, verify that LED0 is flashing on-off, and then click the
   Terminate button () to stop your application running.

The Run button () can be used to switch between projects.
To complete this part of the tutorial, follow these steps:

1. Click the arrow to the right of the Run button and select the
   Run Configuration named illuminate.
2. On your XK-1A, verify that all four LEDs are illuminated.
3. Click the arrow to the right of the Run button and select the
   Run Configuration named flash.
4. On your XK-1A, verify that LED0 is flashing on-off.
5. Modify the source of the flashing LED application to change the value of FLASH_PERIOD from
   20000000 to 40000000.
6. To build and run, just click the Run button.

   The XDE launches the Run Configuration you most recently selected.

7. On your XK-1A, verify that LED0 is flashing on-off at half the rate it was flashing previously,
   and then click the Terminate button () to stop your application running.

To complete this part of the tutorial, perform the following steps:

1. Modify your flashing LED application so that both LED0 and LED1 are
   flashed, with LED0 flashed twice as fast as LED1.

   Show a tip…

   You should output the following pattern to the port led:
   0b0011, 0b0010, 0b0011, 0b0010, 0b0001, 0b0000, 0b0001 and 0b0000.

   Explain the solution in more detail…

   You can define an array of integers an initialize it with the values
   0b0011, 0b0010, 0b0011, 0b0010, 0b0001, 0b0000, 0b0001 and 0b0000. Then
   use a loop to output this sequence of values to the port 4F.

   Show a sample answer…

   #include <xs1.h>
   
   #define FLASH_PERIOD 20000000
   
   out port led = XS1_PORT_4F;
   
   int pattern[] = {0b0011,
                    0b0010,
                    0b0011,
                    0b0010,
                    0b0001,
                    0b0000,
                    0b0001,
                    0b0000};
   
   int main (void) {
     timer tmr;
     unsigned t;
     unsigned i = 0;
     tmr :> t;
     while (1) {
       t += FLASH_PERIOD;
       tmr when timerafter (t) :> void;
       led <: pattern[i];
       i = (i+1) % 8;
     }
     return 0;
   }
   

2. Run your application.
3. On your XK-1A, verify that the two LEDs are flashing at different speeds, and then click the
   Terminate button () to stop your application running.

The program below inputs from one of two timers in a loop.

#include <xs1.h>

#define FLASH_PERIOD 10000000
#define CYCLE_PERIOD 50000000

out port led = XS1_PORT_4F;

int main (void) {
  timer tmrF, tmrC;
  unsigned timeF, timeC;

  tmrF :> timeF;
  tmrC :> timeC;
  while (1) {
    select {
      case tmrF when timerafter(timeF) :> void :
        /* add code to respond to timeout */
        break;
      case tmrC when timerafter(timeC) :> void :
        /* add code to respond to timeout */
        break;
    }
  }
  return 0;
}

Before continuing to the next part of this tutorial, create a new project using this code.

Take a look at the application code in the editor. The first
statement in main inputs the value of the timer tmrF into the
variable timeF, and the second statement inputs the value
of the timer tmrC into the variable timeC.

In the while loop, the select statement waits for the an input on either tmrF or tmrC
to become ready. It then performs the selected input and executes any
code after it up until the keyword break.

If more than one input becomes ready at the same time, only one is executed in
a single iteration of the loop; the other input is selected on the following iteration.

To complete this part of the tutorial, perform the following tasks:

1. Modify the application so that:
   • On each input from tmrC, the program changes which LED is flashed, cycling between all four LEDs in sequence.
   • On each input from tmrF, the program changes the state of the current LED bewteen on and off.

   Show a sample answer…

   #include <xs1.h>
   
   #define FLASH_PERIOD 10000000
   #define CYCLE_PERIOD 50000000
   
   out port led = XS1_PORT_4F;
   
   int main(void) {
   
     unsigned ledOn = 1;
     unsigned ledVal = 1;
     timer tmrF, tmrC;
     unsigned timeF, timeC;
   
     tmrF :> timeF;
     tmrC :> timeC;
   
     while (1) {
       select {
         case tmrF when timerafter(timeF) :> void:
           ledOn = !ledOn;
           if (ledOn)
             led <: ledVal;
               else
             led <: 0;
           timeF += FLASH_PERIOD;
           break;
         case tmrC when timerafter(timeC) :> void:
           ledVal <<= 1;
           if (ledVal == 0x10)
             ledVal = 1;
           timeC += CYCLE_PERIOD;
           break;
       }
     }
     return 0;
   }
   

2. Build your project, create a new Run Configuration, and run it.

   Show reminder…

   Follow these steps:

   1. In the Project Explorer, click your project to select it, and then choose the menu option ProjectBuild Project ().

      If any errors are reported in the Console, double-click an error
      to locate it in the editor, fix the error and then re-build your application.

   2. Choose RunRun Configurations.
   3. In the Run Configurations dialog, in the left panel, double-click XCore Application.
   4. In the right panel, in Name, enter a name for the Run Configuration.
   5. In Project, ensure that your project is displayed. If not,
      click Browse to open the Project Selection dialog, select your project, and then click OK.
   6. In C/C++ Application, click Search Project to open the Program Selection dialog,
      select your application binary, and then click OK.
   7. In Device options, in Run on, select the option hardware, and
      in Target, ensure that the option “XMOS XTAG-2 connected to L1[0]” is
      selected.
   8. Click Run to save your configuration and run it.

      The XDE loads the application binary onto your XK-1A, displaying its progress in
      the Console. When the binary is loaded, the Console is cleared.

3. On your XK-1A, verify that a flashing LED is cycled between the four LEDs, and then click
   the Terminate button () to stop your project running.

To complete this part of the tutorial, perform the following tasks:

1. Add an additional case to the select statement that responds to Button 1 being pressed by
   displaying the string “pressed” on the console, and then waits for Button 1 to be
   released and displays the string “released”.

   Note that Button 1 drives a 1-bit port high. Pressing the button causes it to stop
   driving the port, and releasing results in it driving again.
   You can test for these conditions using the input condition pinseq(0) and pinseq(1).

   Show image of port map…

   

   To print a message to the console, you can include the standard C library header stdio.h and
   use the the library function printf.

   Explain the solution in more detail…

   Follow these steps:

   1. At the top of your source file, include the header file stdio.h.
   2. Define an input port named but1 and initialize it with the value XS1_PORT_1K.
   3. In the select statement, add the following case statement:

      case but1 when pinseq(0) :> void:

   4. In the body of this case, first call the function printf to display the first message; then input from the button when the value sampled on the pin equals 1; and then call printf again to display the second message.

   Show a sample answer…

   #include <xs1.h>
   #include <stdio.h>
   
   #define FLASH_PERIOD 10000000
   #define CYCLE_PERIOD 50000000
   
   out port led = XS1_PORT_4F;
   in port but1 = XS1_PORT_1K;
   
   int main(void) {
   
     unsigned ledOn = 1;
     unsigned ledVal = 1;
     timer tmrF, tmrC;
     unsigned timeF, timeC;
   
     tmrF :> timeF;
     tmrC :> timeC;
   
     while (1) {
       select {
         case tmrF when timerafter(timeF) :> void:
           ledOn = !ledOn;
           if (ledOn)
             led <: ledVal;
               else
             led <: 0;
           timeF += FLASH_PERIOD;
           break;
         case tmrC when timerafter(timeC) :> void:
           ledVal <<= 1;
           if (ledVal == 0x10)
             ledVal = 1;
           timeC += CYCLE_PERIOD;
           break;
         case but1 when pinseq(0) :> void:
           printf("Pressed\n");
           but1 when pinseq(1) :> void;
           printf("Released\n");
           break;
       }
     }
     return 0;
   }
   

2. Run your application.

   A flashing LED should cycle between the four LEDs on your XK-1A.

3. Verify that pressing and holding button BUT1 causes the message “pressed”
   be displayed in the Console and the LEDs to stop flashing. Releasing the
   button should cause the message “released” to be displayed
   and the flashing LED should continue cycling.

   Note that you may need to push the button down firmly on your XK-1A to operate it.

4. In the Console, click the Terminate button () to
   stop your application running.

The program below creates two concurrent threads, which run
two separate tasks independently of each other.

#include <xs1.h>
#include <stdio.h>

#define FLASH_PERIOD 10000000
#define CYCLE_PERIOD 50000000

out port led = XS1_PORT_4F;
in port but1 = XS1_PORT_1K;

void flashLEDs4bitPort(out port led, int flashPeriod, int cyclePeriod) {
  /* Code to flash 4 LEDs connected to a 4-bit port in a cycle */
  unsigned ledOn = 1;
  unsigned ledVal = 1;
  timer tmrF, tmrC;
  unsigned timeF, timeC;

  tmrF :> timeF;
  tmrC :> timeC;

  while (1) {
    select {
      case tmrF when timerafter(timeF) :> void:
        ledOn = !ledOn;
        if (ledOn)
          led <: ledVal;
            else
          led <: 0;
        timeF += FLASH_PERIOD;
        break;
      case tmrC when timerafter(timeC) :> void:
        ledVal <<= 1;
        if (ledVal == 0x10)
          ledVal = 1;
        timeC += CYCLE_PERIOD;
        break;
    }
  }
}

void respondToButton(in port but) {
  /* Code to respond to a button press */
 while (1) {
    but when pinseq(0) :> void;
    printf("Pressed\n");
    but when pinseq(1) :> void;
    printf("Released\n");
  }
}

int main(void) {
  par {
    flashLEDs4bitPort(led, FLASH_PERIOD, CYCLE_PERIOD);
    respondToButton(but1);
  }
  return 0;
}

Before continuing to the next part of this tutorial, create a new project using this code.

Take a look at the code in the editor. In main, the two statements
inside the braces of the par are run concurrently: the current thread
allocates a new hardware thread; the current thread then runs the function
flashLEDs4bitPort; and the new thread runs the function respondToButton.
The L1 device has a total of eight available hardware threads.

To complete this part of the tutorial, perform the following tasks:

1. Build your project, create a new Run Configuration, and run it.
2. Verify that a flashing LED cycles between the four LEDs on your XK-1A.
   Pressing and holding button BUT1 should cause the message “pressed”
   be displayed in the Console and the LEDs should continue to flash.
   Releasing the button should cause the message “released” to be displayed.
3. In the Console, click the Terminate button ()
   to stop your project running.

A channel provides a synchronous, bidirectional link between two threads. It
consists of two channel ends, which two threads can use to interact on demand using
the XC input and output statements.

The program below creates two threads which are connected using a channel, and
communicates a value over this channel.

void snd(chanend cout) {
  cout <: 1;
}

void rcv(chanend cin) {
  int x;
  cin :> x;
}

int main (void) {
  chan c;

  par {
    snd(c);
    rcv(c);
  }

  return 0;
}

The function snd declares a channel end parameter cout, which refers to one
end of a channel. It uses the XC output statement to output the value 1 to a
receiving thread.

The function rcv declares a channel end parameter cin and uses the XC
input statement to input a value to the local variable x.

The function main declares a channel c. The locations of its two channel ends
are established through its use in two statements of the par.

To complete this part of the tutorial, perform the following tasks:

1. Modify your application so that after pressing and releasing button BUT1, the flashing LED
   changes direction. This requires the function respondToButton to communicate with
   the function flashLEDs4bitPort.

   Explain the solution in more detail…

   Follow these steps:

   1. In the function respondToButton:
      • Add a parameter declaration chanend c.
      • After the button is released, output a value 0 to this channel.
   2. In the function flashLEDs4bitPort:
      • Add a parameter declaration chanend c.
      • Add a variable declaration unsigned direction and initialize to 0.
      • Add a case to the select statement that inputs from channel c, and in the body of this case update the variable direction.
      • Modify the body of the case statement that inputs from tmrC so that the next LED flashed depends upon the value of the variable direction.

   Show a sample answer…

   #include <xs1.h>
   #include <stdio.h>
   
   #define FLASH_PERIOD 10000000
   #define CYCLE_PERIOD 50000000
   
   out port led = XS1_PORT_4F;
   in port but1 = XS1_PORT_1K;
   
   void flashLEDs4bitPort(out port led, chanend c, int flashPeriod, int cyclePeriod) {
     /* Code to flash 4 LEDs connected to a 4-bit port in a cycle */
     unsigned ledOn = 1;
     unsigned ledVal = 1;
     unsigned direction = 0;
     timer tmrF, tmrC;
     unsigned timeF, timeC;
   
     tmrF :> timeF;
     tmrC :> timeC;
   
     while (1) {
       select {
         case tmrF when timerafter(timeF) :> void:
           ledOn = !ledOn;
           if (ledOn)
             led <: ledVal;
               else
             led <: 0;
           timeF += FLASH_PERIOD;
           break;
         case tmrC when timerafter(timeC) :> void:
           if (direction) {
             ledVal <<= 1;
             if (ledVal == 0b10000)
               ledVal = 1;
           }
           else {
             ledVal >>= 1;
             if (ledVal == 0)
               ledVal = 0b1000;
           }
           timeC += CYCLE_PERIOD;
           break;
         case c :> int x :
           direction = !direction;
           break;
       }
     }
   }
   
   void respondToButton(in port but, chanend c) {
     /* Code to respond to a button press */
     while (1) {
       but when pinseq(0) :> void;
       printf("Pressed\n");
       but when pinseq(1) :> void;
       printf("Released\n");
       c <: 0;
     }
   }
   
   int main(void) {
     chan c;
     par {
       flashLEDs4bitPort(led, c, FLASH_PERIOD, CYCLE_PERIOD);
       respondToButton(but1, c);
     }
     return 0;
   }
   

2. Run your application.

   A flashing LED should cycle between the four LEDs on one of the XK-1As.

3. On your XK-1A, verify that pressing and releasing button BUT1 causes
   the flashing LED to change direction, and then click the Terminate
   button () to stop your project running.

This part of the tutorial shows you how to put ports and threads on different processor cores. It requires you to have two XK-1As available. Follow these steps:

1. Connect the two XK-1As together.
2. Choose FileNewXDE Source File ().
3. In the New XDE Source File dialog, in File Name, enter the name Dual-XK1A.xn.
4. In Location, ensure that your project folder is selected.
5. Click Finish.

   The XDE creates an empty source file, adds it to your application and opens it in the editor.

6. At the bottom left of the editor, click the Source tab, copy the code in the window below into your new source file, and then save it.

   <?xml version="1.0" encoding="UTF-8"?>
   
   <Network xmlns="http://1m2n3b4v.xmos.com"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://1m2n3b4v.xmos.com http://1m2n3b4v.xmos.com">
   
     <Declarations>
       <Declaration>core stdcore[2]</Declaration>
     </Declarations>
   
     <Packages>
       <Package Id="P1" Type="XS1-L1A-TQ128">
         <Nodes>
           <Node Id="Master" Type="XS1-L1A" InPackageId="0"
                 Oscillator="20MHz" SystemFrequency="400MHz">
             <Boot>
               <Source Location="SPI:bootFlash"/>
               <Bootee NodeId="Slave" Core="0"/>
             </Boot>
             <Core Number="0" Reference="stdcore[0]">
               <Port Location="XS1_PORT_1A" Name="PORT_SPI_MISO"/>
               <Port Location="XS1_PORT_1B" Name="PORT_SPI_SS"/>
               <Port Location="XS1_PORT_1C" Name="PORT_SPI_CLK"/>
               <Port Location="XS1_PORT_1D" Name="PORT_SPI_MOSI"/>
               <Port Location="XS1_PORT_4A" Name="PORT_LED"/>
             </Core>
           </Node>
         </Nodes>
       </Package>
   
       <Package Id="P2" Type="XS1-L1A-TQ128">
         <Nodes>
           <Node Id="Slave" Type="XS1-L1A" InPackageId="0"
                 Oscillator="20Mhz" SystemFrequency="400MHz">
             <Boot>
               <Source Location="XMOSLINK"/>
             </Boot>
             <Core Number="0" Reference="stdcore[1]">
               <Port Location="XS1_PORT_1K" Name="PORT_BUTTON"/>
             </Core>
           </Node>
         </Nodes>
       </Package>
     </Packages>
   
     <Links>
       <Link Encoding="2wire" Delays="4,4">
         <LinkEndpoint NodeId="Master" Link="X0LD"/>
         <LinkEndpoint NodeId="Slave" Link="X0LC"/>
       </Link>
     </Links>
   
     <ExternalDevices>
       <Device NodeId="Master" Core="0" Name="bootFlash"
               Class="SPIFlash" Type="AT25FS010">
         <Attribute Name="PORT_SPI_MISO" Value="PORT_SPI_MISO"/>
         <Attribute Name="PORT_SPI_SS"   Value="PORT_SPI_SS"/>
         <Attribute Name="PORT_SPI_CLK"  Value="PORT_SPI_CLK"/>
         <Attribute Name="PORT_SPI_MOSI" Value="PORT_SPI_MOSI"/>
       </Device>
     </ExternalDevices>
   
     <JTAGChain>
       <JTAGDevice NodeId="Master" Position="0"/>
       <JTAGDevice NodeId="Slave" Position="1"/>
     </JTAGChain>
   
   </Network>
   

7. Make it default target
8. In the Project Explorer, expand your new file to reveal the header file platform.h, and expand this header to reveal the symbols stdcore[0] and stdcore[1].

   These symbols name the two processor cores for your new target, which can be referred to in your XC application.

9. In your XC source file, change the header include file <xs1.h> to <platform.h>.
10. Modify the declaration of the port led to place it on the first core, as shown below:

    on stdcore [0]: out port led = XS1_PORT_4F;

11. Modify the declaration of the port but1 to place it on the second core.
12. Modify the call to the function flashLED to place it on the first core, as shown below:

    on stdcore [0]: flashLED(arguments);

13. Modify the call to the function respondToButton to place it on the second core.
14. In the Project Explorer, expand your project and application folder, and then double-click on the file Makefile.
15. In the Makefile editor, in Target, select the option Dual-XK1A, and then choose FileSave () to save your changes to file.
16. Run your application.

    A flashing LED should cycle between the four LEDs on one of the XK-1As. Pressing and releasing button BUT1 on the other
    XK-1A should cause the direction of the flashing LED to change.

Before writing any code, you need a project to store your files in.
To create a project follow these steps:

1. Choose FileNewxTIMEcomposer Project
   to open the New xTIMEcomposer Project dialog.
2. In Project Name, enter a name such as timing.
3. In Target Hardware, select the option XK-1A Board.
   You don’t need this board to complete the tutorial.
4. In Application Software, select the option Empty XC File.
5. Click Finish.

xTIMEcomposer Studio creates a new project containing an application. It then
adds an empty source file to your application and opens it in the editor.

The program below implements a UART interface:

/*
 * ==========================================================
 * Name        : uart-loopback.xc
 * Description : UART loopback example
 * ==========================================================
 */

#include <xs1.h>
#include <print.h>
#include <platform.h>

#define NUM_BYTES 3
#define BIT_RATE 115200
#define BIT_TIME XS1_TIMER_HZ / BIT_RATE

void txBytes(out port txd, char bytes[], int numBytes);
void txByte(out port txd, int byte);
void rxBytes(in port rxd, char bytes[], int numBytes);
char rxByte(in port rxd);


out port txd = XS1_PORT_1H;
in port rxd = XS1_PORT_1I;

int main()
{
  char transmit[] = { 0b00110101, 0b10101100, 0b11110001 };
  char receive[] = { 0, 0, 0 };

  // Drive port high (inactive) to begin
  txd <: 1;

  par {
    txBytes(txd, transmit, NUM_BYTES);
    rxBytes(rxd, receive, NUM_BYTES);
  }

  return 0;
}

void txBytes(out port txd, char bytes[], int numBytes)
{
  for (int i = 0; i < numBytes; i += 1) {
    txByte(txd, bytes[i]);
  }
  printstrln("txDone"); // Transmit_Done
}

void txByte(out port txd, int byte)
{
  unsigned time;

  // Output start bit
  txd <: 0 @ time; // Endpoint A

  // Output data bits
  for (int i = 0; i < 8; i++) {
    time += BIT_TIME;
    txd @ time <: >> byte; // Endpoint B
  }

  // Output stop bit
  time += BIT_TIME;
  txd @ time <: 1; // Endpoint C

  // Hold stop bit
  time += BIT_TIME;
  txd @ time <: 1; // Endpoint D
}

void rxBytes(in port rxd, char bytes[], int numBytes)
{
  for (int i = 0; i < numBytes; i += 1) {
    bytes[i] = rxByte(rxd);
  }

  printstrln("rxDone");
  for (int i = 0; i < NUM_BYTES; i++) {
    printhexln(bytes[i]);
  }
}

char rxByte(in port rxd)
{
  unsigned byte, time;

  // Wait for start bit
  rxd when pinseq (0) :> void @ time;
  time += BIT_TIME / 2;

  // Input data bits
  for (int i = 0; i < 8; i++) {
    time += BIT_TIME;
    rxd @ time :> >> byte;
  }

  // Input stop bit
  time += BIT_TIME;
  rxd @ time :> void;

  return (byte >> 24);
}

Copy and paste the code into your project, and then choose FileSave to save your changes to file.

Take a look at the code in the editor.

The source code contains a transmitter thread and receiver thread running concurrently.
The UART is configured to operate at a data rate of
115200 bits/s, and the transmitter outputs bytes of data as shown in the diagram below.

The quiescent state of the wire is high.

A byte is sent by first driving a start bit (0), followed by the eight data bits
and finally a stop bit (1). A rate of 115200 bits/s
means that each bit must be driven for a period of 1/115200 = 8.68us.

The transmitter source code has the following structure:

TX ->
TX-BYTE ->
  Output start bit     (Endpoint A)
  Loop-8
    Output data bit    (Endpoint B)
  Output stop bit      (Endpoint C)
  Wait for bit period  (Endpoint D)

When compiled and run on a target device, the time taken to execute
the code between the following pairs of endpoints must always be less than 8.68us:

• Route 1: From Endpoint A to Endpoint B (from the start bit to data bit)
• Route 2: From Endpoint B to Endpoint B (between consecutive data bits)
• Route 3: From Endpoint B to Endpoint C (from the last data bit to the stop bit)
• Route 4: From Endpoint C to Endpoint D (holding the stop bit for the bit period)
• Route 5: Between successive calls to the function txByte

If the constraint on the fifth route is not met, individual bytes will be transmitted correctly,
but the UART will operate at a lower data rate.

More generally, a route consists of the set of all paths through which control can flow between
two endpoints. Each route has a worst-case time, in which branches always follow the path that
takes the longest time to execute. This time must satisfy the constraint for the program to be
guaranteed correct under all possible executions.

To check that the first route meets its timing constraint, follow these steps:

1. In the editor, locate the first output statement (Endpoint A), right-click
   on the endpoint marker in the left margin to bring up a menu, and choose
   Set from endpoint.

   A green dot is displayed in the top-right quarter of the marker.

2. Locate the second output statement (Endpoint B), right-click on its endpoint
   marker and choose Set to endpoint.

   A red dot is displayed in the bottom-right quarter of the marker.

3. Click the Analyze Endpoints button in the main toolbar.

   The timing analyzer identifies a single path between Endpoints A and B, which it times.
   The analyzed route is added to the Routes list in the top panel of the Routes view.
   The bottom panel of the Routes view shows a textual representation of the structure and
   timing for the selected route. The Structure panel in the Visualizations view shows
   a graphical visualization of the structure and timing for the selected route.

   In the Routes list, a red question mark icon is displayed next
   to the route name, indicating that no timing constraint is set.

   

4. Right-click on the route in the Routes list to bring up a menu and choose
   Set timing requirement to open the Requirement box.
5. Enter a value of 8.68, select the unit us and click OK.

   The red question mark is replaced by a green tick , indicating that
   the route meets the specified timing constraint.

6. Hover over the route to view information such as the number of paths and worst-case timing.

To check that the second route meets its timing constraint, follow these steps:

1. Right-click on the marker for Endpoint B to bring up a menu, and choose Set from endpoint.

   The warning triangle generated by the previous Analyze endpoints action obscures the endpoint marker,
   but you can still set a new endpoint by right-clicking on the marker.

   This statement is now set as both the from and to endpoints .

2. Click Analyze Endpoints .

   The timing analyzer identifies the path around the loop. It also attempts to
   identify paths that exit the loop and then later re-enter it.

   The lower panel of the Routes view shows the timing of the route is marked as unresolved,
   which means that some of the paths do not successfully reach the to endpoint. In this case
   the unresolved path ends at the exit system call and cannot therefore possibly re-enter the
   loop, which means it should be excluded from the analysis.

3. Right-click on the first endpoint marker after the loop (Endpoint C) and choose Exclude.

   All paths that pass through this marker are excluded, leaving only one
   path around the loop remaining in the route.

4. In the Routes view, set a timing constraint of 8.68us.

   The status of the route is updated, indicating that the route now meets its timing constraint.

Use the techniques introduced in the previous two sections to check that Route 3 (Endpoint B to Endpoint C) and Route 4 (Endpoint C to Endpoint D) meet their timing constraints.

Once completed, a total of four routes should be displayed in the Routes list.

To check that route 5 meets its timing constraint (between
consecutive byte transmissions), follow these steps:

1. Set the endpoints for a route from Endpoint D to A.
2. In the function txBytes, right-click on the endpoint marker
   following the loop and choose Add to exclusion list.

   The timing analyzer will not attempt to analyze paths outside of the loop.

3. Click Analyze Endpoints in the main toolbar to create the route.
4. In the Routes view, set a timing constraint of 8.68us.

   The status of the route is updated, indicating that the route meets its timing constraint.

   You should have a total of five routes in the Routes list.

To create a timing script and update the source file with
the pragmas required to make the script portable, follow these steps:

1. Click Generate Script button in the main toolbar.

   The Script Options dialog opens.

2. Enter a name for the script (with a .xta extension) in the Script location text box.
3. To change the names of the pragmas added to the source file,
   click the values in the Pragma name fields and edit.
4. Click OK to save the script and update your source code.

   xTIMEcomposer Studio adds the script to your project and opens it in the editor.

   

The next time you compile your program, the timing constraints are checked and any failures
are reported as compilation errors.

Before you write any code, check the LED related information in the GPIO sliceCARD Hardware Guide
.

1. Add the following code to main.xc, which implements a wait function that will be used to delay successive updates of the PWM duty cycle:

   void wait(unsigned wait_cycles) {
     timer tmr;
     unsigned t;
   
     // read the current time
     tmr :> t;
     // event will occur wait_cycles * 10ns in the future
     tmr when timerafter (t+wait_cycles) :> void;
   }
   

   Show where the wait code goes

   

   The function uses a timer to emit an event at some time in the future. Timers use the 100MHz reference clock to provide programmable delays to the software. The 100MHz clock gives 10ns resolution to these delays, allowing the software to precisely control the time at which actions occur. The logical core remains idle until that event happens, thereby saving power.

2. Update the current pwm_controller function with the following code:

   void pwm_controller(chanend c_pwm)
   {
     // PWM period is 10us. 1000 cycles at 10ns (100MHz ref clock)
     int period = 1000;
     // duty_cycle starts at 100% which switches all LEDs off
     // (LEDs active low on GPIO sliceCARD)
     int duty_cycle = 1000;
     // duty cycle step (up or down)
     unsigned step = period / 100;
     // duty_cycle delta.
     int delta = -step; // start with increasing brightness
   
     // output the PWM period length to a channel
     c_pwm <: period;
     // output the PWM duty cycle length to a channel
     c_pwm <: duty_cycle;
   
     while(1) {
       // update the duty cycle length
       c_pwm <: duty_cycle;
   
       wait(XS1_TIMER_HZ/100); // 0.01 s
       duty_cycle += delta;
       if(duty_cycle > period) {
         delta = -step; // increase brightness
         duty_cycle = period;
       }
       else if(duty_cycle < 0) {
         delta = step; // decrease brightness
         duty_cycle = 0;
       }
     }
   }
   

   Show where the pwm_controller code goes

   

   The new pwm_controller updates the PWM logical core, by periodically sending new PWM settings to it over the channel. There is a delay of 10ms between each update to the PWM core. The step between every successive duty cycle is 1/100 of a PWM period which means the time to go from 0 to 100% duty (LED fully on to LED fully off) is 100 * 10ms = 1 second.

3. Click PWM in the Project Explorer and select Project > Build Project.
4. Click Run.

   The four LEDs are dimmed up and down every 2 seconds.

You can extend this simple example to any real-time task. Using the precise 100MHz timer, together with the deterministic execution of xCORE multicore microcontrollers makes it easy to accurately control your real-time tasks.

The module supports multiple I2C Masters but you only need one Master (the xCORE) in this application.

The I2C component has a simple set of APIs to configure it, and to read and write data via I2C. These APIs execute functions which implement the I2C interface.

You will use the function i2c_master_write_reg to configure the ADC at startup. Using the tx8 function, it writes the Slave device ID, address and then a list of bytes.

1. Open module_i2c_master/src/i2c-mm.xc.
2. Find the i2c_master_write_reg function.
3. Double click on the first instance of tx8 to mark it.
4. Right-click on the marked tx8 and select Open Declaration.

   The Editor window jumps to the tx8 function that implements the I2C protocol for writing a single byte.

   The HighPulse() function sends each bit of the byte in a loop. The timing of the edges of the I2C SCL (clock) and I2C SDA (data) signals are controlled by the function waitQuarter which, like the wait function you implemented previously, uses a timer to emit an event in the future upon which the signal level is changed.

This is a basic example of a hardware interface implemented completely in software running on a logical core.

This section shows how to modify the PWM controller function so that it reads the ADC via I2C every period of the LED cycle.

1. Declare the variables you need above your printstr statement, and use the i2c_master_write_reg function to initialize the ADC.

   // I2C write data
     unsigned char wr_data[1]={0x13};
     unsigned char rd_data[2];
     int adc_value;
   
     //Write configuration information to ADC
     i2c_master_write_reg(0x28, 0x00, wr_data, 1, i2cOne);
   
     printstr("Welcome to the XMOS PWM tutorial\n");
   

   Show where the i2c_master_write_reg function goes

   
2. Add the following code to use the I2C_master_rx function to read from the ADC at the end of the PWM cycle period. It should be inserted after the duty cycle is incremented (duty_cycle += delta;)

   if (duty_cycle > period)
   {
     //Read ADC value using I2C read
   
     rd_data[0]=rd_data[0]&0x0F;
     i2c_master_rx(0x28, rd_data, 2, i2cOne);
     rd_data[0]=rd_data[0]&0x0F;
     adc_value=(rd_data[0]<<6)|(rd_data[1]>>2);
     printstr("Temperature is :");
     printintln(linear_interpolation(adc_value));
   

   Show where the i2c_master_rx code goes

   
3. Add the linear interpolation function above your pwm_controller. This function is used to convert the ADC value to a temperature value.

   int TEMPERATURE_LUT[][2]= //Temperature Look up table
   {
     {-10,845},{-5,808},{0,765},{5,718},{10,668},
     {15,614},{20,559},{25,504},{30,450},{35,399},
     {40,352},{45,308},{50,269},{55,233},{60,202}
   };
   
   int linear_interpolation(int adc_value)
   {
     int i=0,x1,y1,x2,y2,temper;
     while(adc_value<TEMPERATURE_LUT[i][1])
     {
       i++;
     }
     // Calculating Linear interpolation using the formula
     // y=y1+(x-x1)*(y2-y1)/(x2-x1)
     x1=TEMPERATURE_LUT[i-1][1];
     y1=TEMPERATURE_LUT[i-1][0];
     x2=TEMPERATURE_LUT[i][1];
     y2=TEMPERATURE_LUT[i][0];
     temper=y1+(((adc_value-x1)*(y2-y1))/(x2-x1));
   
     return temper;
   }
   

   Show where the interpolation function goes

   
4. Build and run your application.

   Every two seconds the temperature is printed to your console. Check that the temperature is printed to your console.

   Output temperature reading

   

Before writing any code, you need a project to store your files in. To create a new project follow these steps:

1. Choose FileNewXDE Project () to open the New XDE Project dialog.

   Alternatively, click here to automate steps 1, 3 and 4.

2. In Project Name, enter a name such as illuminate.
3. In Target Hardware, select the option XC-1A Development Board.
4. In Application Software, select the option Empty XC File.
5. Click Finish.

   The XDE creates a new project, then adds an empty source file to the project and opens it in the editor.

   

The program below illuminates an LED on an XC-1A.

#include <xs1.h>

out port bled = XS1_PORT_4C;

int main () {
  bled <: 0b0001;
  while (1)
    ;
  return 0;
}

Copy and paste the code into your project, and then choose FileSave () to save your changes to file.

Take a look at the code in the editor. The declaration

out port bled = XS1_PORT_4C;

declares an output port named bled, which refers to the 4-bit port 4C. On the XC-1A, the I/O pins of
port 4C are connected to the LEDs positioned next to the four press-buttons (collectively referred to as button-LEDs) that contain green diodes.

Show image of port map…

Ports must be declared as global variables. The optional out qualifier allows the compiler to check for correct usage, thereby helping to reduce programming errors.

XC input and output statements make it easy to express I/O operations on ports.
The statement

bled <: 0b0001;

causes the value specified to the right of <: to be output to the port specified
to its left (led). The port then drives LED next to button A high and the other LEDs low,
causing the LED to illuminate green and the other LEDs to remain off.

The empty while loop prevents the program from terminating,
which ensures that the LED remains illuminated.

To build and run your project, follow these steps:

1. In the Project Explorer, click your project to select it, and then choose the menu option ProjectBuild Project ().

   The XDE displays its progress in the Console. When the build is complete,
   the XDE adds the compiled binary file to the subfolder bin/Debug.

   

2. Choose RunRun Configurations.
3. In the Run Configurations dialog, in the left panel, double-click XCore Application.
4. In the right panel, in Name, enter the name illuminate.
5. In Project, ensure that your project is displayed. If not,
   click Browse to open the Project Selection dialog, select your project, and then click OK.
6. In C/C++ Application, click Search Project to open the Program Selection dialog,
   select your application binary, and then click OK.
7. In Device options, in Run on, select the option hardware, and
   in Target, ensure that the option “XMOS XC-1A Board” is
   selected.

   If your hardware is not displayed, ensure that your XC-1A is
   connected to your PC, and then click Refresh list.

8. Click Run to save your configuration and run it.

   The XDE loads the binary onto your XC-1A, displaying its progress in
   the Console. When the binary is loaded, the Console is cleared.

9. On your XC-1A, verify that BUTTONLED A is illuminated green.
10. In the Console, click the Terminate button () to
    stop your application running.

To complete this part of the tutorial, perform the following steps:

1. Modify your code so that it illuminates all four BUTTONLEDs.

   You should change the value output to the port bled so that all four LEDs are driven high.

   #include <xs1.h>
   
   out port led = XS1_PORT_4C;
   
   int main () {
     bled <: 0b1111;
     while (1)
       ;
     return 0;
   }
   

2. Click the Run button () to reload your last Run Configuration.

   The XDE determines that your source code has been updated and re-builds it,
   displaying progress in the Console.

   If your code contains errors, the XDE displays a dialog asking if you want to
   continue launching the application. Click No, locate the first error in the
   Console and double-click it to go to the offending line in the editor. When
   you have fixed all errors, re-run your application.

3. On your XC-1A, verify that all four BUTTONLEDs are illuminated, and then click the
   Terminate button () to stop your application running.

The program below flashes a single LED on an XC-1A.

#include <xs1.h>

#define FLASH_PERIOD 20000000

out port bled = XS1_PORT_4C;

int main (void) {
  timer tmr;
  unsigned isOn = 1;
  unsigned t;
  tmr :> t;
  while (1) {
    bled <: isOn;
    t += FLASH_PERIOD;
    tmr when timerafter (t) :> void;
    isOn = !isOn;
  }
  return 0;
}

Copy and paste the code into your project, and then choose FileSave () to save your changes to file.

Take a look at the code in the editor. The declaration

timer tmr;

declares a variable named tmr, and allocates an available hardware timer. Each core on the
G4 device provides 10 timers, which can be used to determine when an event happens, or to
delay execution until a particular time. Each timer contains a 32-bit
counter that is incremented at 100MHz and whose value can be input at any time.

The statement

tmr :> t;

inputs the value of tmr‘s counter into the variable t. Having recorded the
current time, the statement

t += FLASH_PERIOD;

increments this value by the required delay, and the statement

tmr when timerafter(t) :> void;

delays inputting a value until the specified time is reached. The input
value is not needed, which is expressed as an input to void.

To build and run your application, follow these steps:

1. In the Project Explorer, click your project to select it, and then choose the menu option ProjectBuild Project ().

   The XDE builds your project, displaying its progress in the Console.
   When the build is complete, the XDE adds the compiled binary file to the application subfolder bin/Debug.

2. Create a new Run Configuration for your project named flash, and run it.

   Show reminder…

   Follow these steps:

   1. Choose RunRun Configurations.
   2. In the Run Configurations dialog, in the left panel, double-click XCore Application.
   3. In the right panel, in Name, enter the name flash.
   4. In Project, ensure that your project is displayed. If not,
      click Browse to open the Project Selection dialog, select your project, and then click OK.
   5. In Device options, in Run on, select the option hardware, and
      in Target, ensure that the option “XMOS XC-1A Board” is
      selected.
   6. Click Run to save your configuration and run it.

      The XDE loads the binary onto your XC-1A, displaying its progress in
      the Console. When the binary is loaded, the Console is cleared.

3. On your XC-1A, verify that BUTTONLEDA is flashing on-off, and then click the
   Terminate button () to stop your application running.

The Run button () can be used to switch between projects.
To complete this part of the tutorial, follow these steps:

1. Click the arrow to the right of the Run button and select the
   Run Configuration named illuminate.
2. On your XC-1A, verify that all four LEDs are illuminated.
3. Click the arrow to the right of the Run button and select the
   Run Configuration named flash.
4. On your XC-1A, verify that BUTTONLEDA is flashing on-off.
5. Modify the source of the flashing LED application to change the value of FLASH_PERIOD from
   20000000 to 40000000.
6. To build and run, just click the Run button.

   The XDE launches the Run Configuration you most recently selected.

7. On your XC-1A, verify that BUTTONLEDA is flashing on-off at half the rate it was flashing previously,
   and then click the Terminate button () to stop your application running.

To complete this part of the tutorial, perform the following steps:

1. Modify your flashing LED application so that both BUTTONLEDA and BUTTONLEDB are flashed,
   with BUTTONLEDA flashed twice as fast as BUTTONLEDB.

   Show a tip…

   You should output the following pattern to the port bled:
   0b0011, 0b0010, 0b0011, 0b0010, 0b0001, 0b0000, 0b0001 and 0b0000.

   Explain the solution in more detail…

   You can define an array of integers an initialize it with the values
   0b0011, 0b0010, 0b0011, 0b0010, 0b0001, 0b0000, 0b0001 and 0b0000. Then
   use a loop to output this sequence of values to the port 4C.

   Show a sample answer…

   #include <xs1.h>
   
   #define FLASH_PERIOD 20000000
   
   out port bled = XS1_PORT_4C;
   
   int pattern[] = {0b0011,
                    0b0010,
                    0b0011,
                    0b0010,
                    0b0001,
                    0b0000,
                    0b0001,
                    0b0000};
   
   int main (void) {
     timer tmr;
     unsigned t;
     unsigned i = 0;
     tmr :> t;
     while (1) {
       t += FLASH_PERIOD;
       tmr when timerafter (t) :> void;
       bled <: pattern[i];
       i = (i+1) % 8;
     }
     return 0;
   }
   

2. Run your application.
3. On your XC-1A, verify that the two LEDs are flashing at different speeds, and then click the
   Terminate button () to stop your application running.

The program below inputs from one of two timers in a loop.

#include <xs1.h>
#define BIT_RATE 115200
#define BIT_TIME XS1_TIMER_HZ / BIT_RATE
out port TXD = XS1_PORT_1H;

int main(){
  return 0;
}

void txByte (out port TXD, int byte) {
  unsigned time;
  timer t;

  /* input initial time */
  t :> time;

  /* output start bit */
  TXD <: 0;
  time += BIT_TIME;
  t when timerafter (time) :> void;

  /* output data bits */
  for (int i=0; i <8; i++) {
      TXD <: >> byte;
      time += BIT_TIME;
      t when timerafter (time) :> void;
  }

  /* output stop bit */
  TXD <: 1;
  time += BIT_TIME;
  t when timerafter (time) :> void;
}

Before continuing to the next part of this tutorial, create a new project using this code.

Show reminder…

To complete this part of the tutorial, perform the following steps:

1. Load a terminal emulator program on your PC and connect it to the virtual COM
   port provided by the XC-1A. A simple terminal emulator is available from the
   XMOS community website.
2. Complete the program by declaring a port for the UART and by writing a main
   function that outputs the message Hello World! to this port.

   You can find the relevant port in the XC-1A Hardware Manual
   .

3. Run your application.
4. The terminal should receive and display the message.

The program below flashes a single CLOCKLED.

#include <platform.h>
#define PERIOD 20000000

out port cled0 = PORT_CLOCKLED_0;
out port cled1 = PORT_CLOCKLED_1;
out port cled2 = PORT_CLOCKLED_2;
out port cled3 = PORT_CLOCKLED_3;
out port cledG = PORT_CLOCKLED_SELG;
out port cledR = PORT_CLOCKLED_SELR;

void flashLED (out port led, int period);

int main (void) {
  par {
    on stdcore [0]: { cledG <: 1;
                        flashLED (cled0 , PERIOD);
                    }
    on stdcore [1]: flashLED (cled1, PERIOD);
    on stdcore [2]: flashLED (cled2, PERIOD);
    on stdcore [3]: flashLED (cled3, PERIOD);
  }
  return 0;
}

void flashLED (out port led, int period){
}

Before continuing to the next part of this tutorial, create a new project using this code.

The schematic for the 12 clock-LEDs is shown below; the location of the ports are shown in
the XC-1A Hardware Manual
.

The LED anodes are connected to four 8-bit ports: PORT_CLOCKLED_0 on XCore 0, PORT_CLOCKLED_1 on XCore 1,
PORT_CLOCKLED_3 on XCore 3 and PORT_CLOCKLED_4 on XCore 4. The LED cathodes are connected to
two 1-bit ports on XCore 0: PORT_CLOCKLED_SELG (green) and PORT_CLOCKLED_SELR (red). This means that
two pins must be driven to illuminate a clock-LED.

The par statement provides a simple way to create concurrent threads that run
independently of one another.

The on statement instructs the compiler on which processor each port is connected and
each thread is executed. An on statement may only be used with threads created by main,
in which case main may contain only channel declarations, a single par statement
and an optional return statement.

The program creates four concurrent threads, each running an instance of a function flashLED.

To complete this part of the tutorial, perform the following tasks:

1. Implement the body of the function flashLED so that it flashes a single LED.
   Note that the pins are connected to bits 4–6 on the 8-bit port.
2. Build your application, create a new Run Configuration, and run it.
3. On your XC-1A, verify that four LEDs on the clockface flash continually at a fixed rate, and then click
   the Terminate button () to stop your application running.

To complete this part of the tutorial, perform the following tasks:

1. Experiment with different period values for each of the threads so that the threads
   can be seen to be operating independently of one another.

The program below flashes a single CLOCKLED.

#include <platform.h>
#define PERIOD 20000000

out port cled0 = PORT_CLOCKLED_0;
out port cled1 = PORT_CLOCKLED_1;
out port cled2 = PORT_CLOCKLED_2;
out port cled3 = PORT_CLOCKLED_3;
out port cledG = PORT_CLOCKLED_SELG;
out port cledR = PORT_CLOCKLED_SELR;

void tokenFlash (chanend left, chanend right, out port led, int delay, int isMaster) {
  timer tmr;
  unsigned t;

  if (isMaster) /* master inserts token into ring */
    right <: 1;

  while (1) {
    int token;
    left :> token; /* input token from left neighbor */
    led <: 1;
    tmr :> t;
    tmr when timerafter (t+ delay ) :> void;
    led <: 0;
    right <: token; /* output token to right neighbor */
  }
}

int main (void) {
  chan c0, c1, c2, c3;
  par {
    on stdcore [0]: { cledG <: 1;
                      tokenFlash (c0, c1, cled0, PERIOD, 1);
                    }
    on stdcore [1]: tokenFlash (c1, c2, cled1, PERIOD, 0);
    // other cores
  }
  return 0;
}

Before continuing to the next part of this tutorial, create a new project using this code.

An XC channel provides a synchronous, bidirectional link between two threads. It
consists of two channel ends, which two threads can use to interact on demand using
the XC input and output statements.

The function tokenFlash implements a component of the token ring illustrated below,
repeatedly inputting a token from its left neighbor, flashing an LED and outputting
the token to its right neighbor:

The first two function parameters are channel ends, the third an LED port and the
fourth a Boolean value indicating whether or not the thread executing the function is
the designated master. The master inserts a token into the ring.

The XC input and output statements are used to communicate the token between
threads. As channels are synchronous, each output operation blocks until a matching
input operation is ready, ensuring that precisely one thread has possession of the
token at any time.

The main function constructs the token ring. A channel is declared using the keyword
chan. The locations of its two channel ends are established through its use in two
statements of the par.

A total of four channels are required to complete this program, each of which must
be used in two threads: once as a left argument and once as a right argument to the
function tokenFlash.

To complete this part of the tutorial, perform the following tasks:

1. Modify the function tokenFlash so that it flashes each of the three LEDs connected
   to its port in sequence, add the required port declarations and complete the definition
   of main.
2. Build your application, create a new Run Configuration, and run it.
3. On your XC-1A, verify that the 12 LEDs each flash in sequence as the token cycles around the four threads,
   and then click the Terminate button () to stop your application running.

A select statement is used to respond to one of a set of inputs, depending on which
becomes ready first. If more than one input becomes ready at the same time, only
one is executed.

The function below waits for either a token to be received, in which case it passes it
on, or for a button to be pressed.

void buttonListener ( chanend left ,
                      chanend right ,
                      in port button ,
                      out port g,
                      out port r) {
  int token ;
  int isGreen = 1;
  g <: 1;
  while (1)
    select {
      case left :> token :
      /* pass token on */
        right <: token ;
      break ;
      case button when pinsneq (0xf):> void :
        /* change color *
        ...
      break ;
  }
}

The guarded input statement

case left :> token :

becomes ready when the token arrives, in which case it is input and passed to the
next thread. The guard

case button when pinsneq (0xf):> void :

becomes ready when the value on the pins connected to the port button is not equal
to the bit pattern 0xf. This signifies that the button was pressed.

To finish this part of the tutorial, complete the following tasks which build on the
program from the previous section:

1. Add a declaration for the button port (see the XC-1A Hardware Manual
   for details of the initializer).
2. Complete the function buttonListener and integrate it into the token ring.

   Note that you cannot output to a port in two concurrent threads, nor can you write
   the same variable in parallel. These restrictions prevent common programming
   errors such as race conditions, and ensure that the two threads can be run on any
   two cores, regardless of whether they share memory.

3. Run your application.

   Press one of the buttons to change the colour of an LED as it circulates around the clock.

4. On your XC-1A, verify that pressing a button changes the colour of an LED as it circulates,
   and then click the Terminate button () to stop your application running.