Create a new component

How to create a new component? Below is an introduction of how to create a new project in CoIDE 2.0 Beta version, using STM32F407 discovery board as an example.

Document filing of the component

the attainment of the necessary tools and component templates

needed software tool

To develop a high-quality component drive, the corresponding instruction documents is essential. Here we list all the software tools that will be used.

1. Doxygen (to create a document automatically)
2. ant (to execute the batch file written by coocox)
3. COIDE (to compile the project )

the attainment of component templates

You can download component templates in our website website, or use the build-in component project templates from updated CoIDE. It’s very easy to create a component project, same way with creating a normal one. When you select an IC, CoIDE will create a template for the user after he/she choose New Component Project.
Attention:the name of component project template is also the name of components.

For example,the name the engineer who create the component input is "ILI9325". Clock it, then we will see the documents we need, what you should is too fulfill the documents.

Click the bottom"Create a Doc",then select "setting", you can check the basic parts of the component.

the documents organization of component template and the expecting effect

the documents organization of template

Among the catalogue of new project, we can find component project template made by CoIDE. Now, let’s see the contents of the template and the relations with catalogue.

Their functions are:

• assets: they are used to store pictures or PDF quoted by file instruction.
• doxygen: they are used to store configuration files and batching files that related to doxygen sorted by coocox.
• helloworld: they are used to store original file of the example project we wrote for components.
• output: they are used to store website file formed by doxygen and procedure files formed by compiler.
• test: they are used to store original file of the test project we wrote for components.
• README md: this file is our introduction file in the component home page.

reach the expecting effect:

We can open index.html file under component_driver\output\doxygen\html in the example template to check sorted document. Here are component pile homepage sorted by component_driver. We can check what we are interested in through the right side navigation bar.

From this picture it is not hard to find that we divide component file into four parts:

• API Reference: all the component API function.
• Invoker Configuration:configuration information we need to focus on when using;
• Enumeration:the enumeration we use when configuring, including Enum users care and Enum users don’t care.

concrete stops for creating a document and separating a interface.

Hw_Component.h write a file

We recommend following steps to carry out separation.

Original file and header file before revising are as shown in the picture below.

On the basic of the former file, we create two files : Hw_ILI9325.h and ILI9325_config.h

　 The driver we wrote before almost has no register. The meaning of extracting register is that once we need to use one of the functions, we don’t need to check the register. We suggest that the registers should be divided into two types: the type we don’t need to care when using , another type we need to use when using.

We suggest you add annotation for each macro, the format is as follow:

#define ILI9325_GRAM_ADDR_SET_REG1                0x20 ///< GRAM horizontal Address
#define ILI9325_GRAM_ADDR_SET_REG2                0x21 ///< GRAM Vertical Address
#define ILI9325_GRAM_ACCESS_PORT_REG              0x22 ///< Write/Read Data to GRAM

We should emphasize that we use the doxygen annotation style in this place. So here comes a question ,shall we learn the doxygen annotation style? Coocox tells us, from our experience, to forming pretty doxygen file, there are only four points we should know.

The macro definition we mentioned is one of them. Easy, right? At the following introduction we will show you another three points.

Write a Component_config.h.example

We mentioned that this file is used to save related templates of configuration information. But if this component has not been finished, we suggest you adopt Component_config.h file format and let it be used in the compile of project.

The configuration we mentioned here means a microscopical definition of Macro in a functional way. Mostly ,we will put the work model and interface information of device into this file. Here are some information about ILI9325.

write a Component.h

This file is a significant one. In order to keep the compatibility with the program we wrote before, we will define the macro definition,which we may use in application program, in this place. We also have function declaration. We still suggest you group the function declaration. If you have ever used the third party middleware, we suggest you divide them into three groups: Downward transplantation related function, upward transplantation related function, the upper function when used independently.

Below here is a brief introduction of how to group documents.

//*****************************************************************************
//
//! \addtogroup ILI9325_PORT_API Exported function
//! \brief Downward migration is a function of the need to care about the interface 
//! @{ 
//
//*****************************************************************************
void LCD_Port_Configure(void);
void LCD_FSMC_Configure(void);
void ILI9325_WriteREG(u8 Reg, u16 Value);
u16  ILI9325_ReadREG(u8 Reg);
void ILI9325_WriteData(u16 RGB_Code);
u16  ILI9325_ReadData(void);
void Delay_ms(u32 nms);
//*****************************************************************************
//
//! @}
//
//*****************************************************************************

The code above is the second point we prepared for you to use doxygen document filing, that is grouping. Creating a new group is similar with defining a variable quantity in C language.

• "\addtogroup": key of grouping. It is similar to the key in C language, being recognized by doxygen.
• "ILI9325_PORT_API": tag of grouping, it is similar to the name of variable quantity in C language.
• "Exported function": name of grouping, it is similar to the value of variable quantity in C language.
• "\brief": demonstrate parts of key. The instruction we add will be showed when formed a document.

The same with C language, we can only define it rather than valuing it . At this moment, doxygen will check all the original files automatically and declare here. If they haven’t been named, doxygen will take group name as the value. And they will be shown at the navigation bar.

writhe a Component.c document

This file is a difficult part. All our functions will be realized here, and we need to add instructions for each function.

//*****************************************************************************
//
//! \brief This function is used to value written in to register
//!
//! \param Reg   : ILI9325 Register number
//!        Value : The value will write to the register
//!
//! \ref ILI9325_Registers 
//!
//! \note None
//!
//! \return None.
//
//*****************************************************************************
void ILI9325_WriteREG(u8 Reg, u16 Value)
{
    #if(LCD_USE_DRIVE_MODE == LCD_FSMC_Mode)    
    {
        LCD_REG = Reg;
        LCD_RAM = Value;
    }
    #else
    {    
        #if(LCD_USE_DATA_BUS_MODE == LCD_16_Bit_Mode)
        {

        }
        #else
        {

        }
        #endif

    }
    #endif
}

The function annotation we use here is the third point we conclude. It is recommended by coocox. One thing we need to point out is that we explained "\ref ILI9325_Registers ". The advantage of using this is that the interlinkage can be produced automatically to the related place when creating a document:

• "\ref ":doxygen key, used to remind doxygen that you can create a linkage in this place.
• "ILI9325_Registers": name of the group that need to be linked to.

With this ,we can easily get the information we want.

Until now, we almost finished documents filing. But we have only one layer for a group directory. Then what we should do is adding an upper directory for each document. In this action,we must guarantee all the files are in the same group, otherwise the directory would be in chaos. With the coocox standard for grouping upper layer ,the whole components have been grouped as following:

ILI9325
│   
├───API Reference
│   └───Exported API
│   └─── ...
├───Configuration
│   └───LCD Size
│   └─── ...
├───Enumeration
│   └───ILI9325 registers
│   └─── ...
└───Hello World
    └───test example
    └─── ...

write the component homepage

We put homepage to the root directory: README.md

We use the Markdown file at homepage. We use Markdown language to write this homepage.

When writing homepage documents, we should notice:use following statement to tell doxygen which directory should be choose to put contents in.

@if (DOXYGEN_PROJECT)
@defgroup ILI9325_Component
@endif

Create an example project in COIDE

So far we almost finish creating a new component. Then let’s talk about how to write example project and test project.

We will revise some files under the directory of helloworld. The revised directory files are as following:

helloworld
 │   
 └───test_example
        ILI9325_config.h    ===================> example configure file
        test_example.coproj ===================> test example project
        test_example.c      ===================> test example file
        README.md           ===================> This document is used for example simple instructions

When we write the example instruction document, we should change "@defgroup ILI9325_HelloWorld_HelloWorld_1 HelloWorld_1" to the real group tag and name.

@defgroup @defgroup ILI9325_HelloWorld_HelloWorld_1 HelloWorld_1

Otherwise, the instruction document can not add any component project.

produce and submit component documents.

use command line to produce a document and check it by browser

Open command line under doxygen and input "ant",then press the return button.

C:\Users\Sam\Desktop\New_component\ILI9325\doxygen>ant

Then, under the directory of C:\Users\Sam\Desktop\New_component\ILI9325\output\doxygen\html, we can find"index.html" and check the component document we wrote.

Check it directly in COIDE

Click "create doc" button, then click "setting" button, we can check component document in COIDE.