3.1. Deploy to new platform in ten minutes

3.1.1. How to choose a platform that can run pikascript

  • PikaScript can run on all bare metal and operating systems that support libc.

  • The compiler needs to be able to support the C99 standard.

  • Supports 32bit/64bit kernel, does not support 8bit kernel.

  • resource occupancy

    • If it is an arm kernel, considering the resource consumption of the expansion module, it should be equipped with a minimum of 64k flash and 8k ram.

    • If it is a risc-v kernel, you need 128k flash and 8k ram , because of the gcc optimization of the risc-v kernel and the problem of code density, the code size is much larger than that of the arm kernel.

    • If it is other kernel, you can refer to the configuration requirements of risc-v.

  • If it is a PC/server platform, linux/windows can be used.

3.1.2. Deployment operation process

In this document, we will describe how to deploy PikaScript for new platforms.

PikaScript has almost no global variables and macros, and only depends on the standard library, so it is very easy to deploy PikaScript for new platforms.

Here are the specific steps to deploy PikaScript

3.1.2.1. Prepare template project

Your template project just needs to include a serial port initialization that supports printf, and then you can happily use pikascript.

The usual script interpreters rely on the operating system and file system, and pikascript does not need these, if you have deployed other scripting engines, you will find that PikaScrip has real super Lightweight features.

3.1.2.2. Get PikaScript source code and toolset

To get PikaScsript, you can use the pika package manager (option 1), or use the project generator on the official website (option 2).

Option 2 is an automated version of Option 1. It is recommended that newbies use Option 1 when deploying for the first time to familiarize themselves with the package manager.

3.1.2.2.1. Scenario 1 Using pika package manager

3.1.2.2.1.1. Download PikaScript Package Manager

PikaScript package manager can help you pull all source code and tools needed by pikascript, and provide version selection function, which is convenient for you to switch versions.

And the PikaScript package manager uses gitee source, which can be used smoothly in the mainland, does not require scientific Internet access.

Enter the PikaScript main repository

https://github.com/pikastech/pikascript

or:

https://gitee.com/lyon1998/pikascript

Download the PikaScript package manager PikaPackage.exe

https://user-images.githubusercontent.com/88232613/171088180-661d9b90-f6f9-4e75-9927-6e5d4917e8ea.png

Then open the project you want to deploy, create a new pikascript folder in the root directory of the project, and copy PikaPackage.exe into it.

_images/142019778-c727336c-9b6a-4a82-b813-1671f4120152.png

3.1.2.2.1.2. Pull source code

Next, with the help of PikaPackage.exe, we can easily pull the source code and modules of the specified version.

Pull the source code and modules through a requestment.txt file.

If you are familiar with python’s pip package manager, you will find that the requestment.txt file format of pikascript is the same as that of pip.

Create a new requestment.txt file in the pikascript folder of the project, and write the following content.

  1. pikascript-core==v1.8.0
  2. PikaStdLib==v1.8.0

The requestment.txt file indicates that the v1.8.0 version of the pikascript interpreter kernel and the v1.8.0 version of the standard library are used.

The interpreter kernel and the standard library are required options.

The version numbers of the two can be the same, and the other Modules can be added selectively, on initial deployment, only the kernel and standard libraries should be added to avoid compatibility issues.

Currently only the == symbol is supported, which means strictly matching the version number. There is also a special version of latest, which means to pull the latest module.

This latest refers to the latest version of the master branch in the pikascript repository.

If you are a user of the module rather than a developer, please be careful not to use the latest version. Because the latest version is constantly changing, newer versions of modules may cause compatibility issues.

You can copy the requestment.txt kernel and standard library version of stm32g030, which is an officially supported development board The version used by Pika Pie-Zero.

And all optional versions can be viewed in the packages.toml file.

The lts2021 version refers to the long-term support version released at the end of 2021, and the support period is within 2022.

The usual version number is v1.x.x, the lts2021 version is based on v1.3.5 with stability patches.

The pikascript folder now has two files, pikaPackage.exe and requestment.txt. Double-click to run pikaPackage.exe, and the source code and modules specified in requestmemt.txt will be pulled down.

_images/142022949-54585060-8612-42a8-a585-8c3e514a8be3.png

The pulled files are shown in the figure below, pikascript-core is the kernel source code, pikascript-lib is the module library, pikascript-api is the module API, and rust-msc-latest-win10.exe is the dedicated precompiler for pikascript.

/projects/pikascript-1.9-en/bbe13d814c17a80cd2606835d2518972.png

If you want to upgrade the version, modify the version number in requestment.txt and run pikaPackage.exe again, the original version will be overwritten.

After pulling the source code, the next step is to write the python script that pikascript runs.

We create a new main.py file in the pikascript folder.

Then write:

  1. import PikaStdLib
  3. print('hello PikaScript!')

Among them, import PikaStdLib means importing the standard library.

The standard library must be imported, even if it is not used directly, and print('hello PikaScript!') is used to test whether pikascript is started normally.

3.1.2.2.2. Option 2 Use the project generator on the official website

Enter the official website: http://pikascript.com/

https://user-images.githubusercontent.com/88232613/171088424-6cae6aff-6199-488d-9c1f-2c3ad4a9d9e2.png

Select the template for the platform, and then click “Start Generation” to get the default reqeustment.txt, main.py, and pikaPackages.exe.

When the project is generated, the source code and tools are automatically packaged.

3.1.2.3. Precompiled modules

Next, run rust-msc-latest-win10.exe to precompile main.py and imported modules into pikascript api files.

The precompiled files are in the pikascript-api folder.

https://user-images.githubusercontent.com/88232613/171088576-8bbb420b-c2c5-4f01-b280-f88d45c89f9e.png

We open the pikascript-api folder and find that there are some .c and .h files in it, which means that the precompile is successful.

The pikascript precompiler can precompile C modules into .c and .h files.

_images/1644385073271-a39b8d40-f722-4a0c-9b50-e7357f0eae48.png

3.1.2.4. Add source code

Create three new groups in Project, it is recommended to name them pikascript-core, pikascript-api and pikascript-lib

_images/130967351-597b8f6b-cc4e-4bc3-9cb6-2f335e5dccea.png

Then add all the .c files in the three subfolders in the pikascript folder to the keil project (the actual number of .c files may be inconsistent with the screenshots, just add them all.)

_images/130971776-41d8c940-42d0-407d-872e-53525ce299a6.png

Then add include paths for pikascript-core and pikascript-api folders.

_images/130967813-94016b8a-e408-4b49-b1e1-76a5df5fe984.png

_images/130967949-8399c65b-5584-4674-a947-e40103d953ea.png

3.1.2.5. Adjust stack

Open the project’s startup file, in stm32, this is a startup_stm32xxxx.s file, and on other platforms, you have to figure out how to adjust the stack yourself.

_images/130966276-24014a0a-90a6-4bd7-96b7-fde54806b8c3.png

It is recommended to allocate 4K stack space and 16K heap space, and at least 1K stack space and 4K heap space need to be allocated

4K stack space corresponds to 0x1000, 16K heap space corresponds to 0x4000, as shown in the following figure

_images/130967178-a985a4f5-730c-47fd-9317-68f33bc00066.png

3.1.2.6. Start PikaScript

Add the startup code of PikaScript in the initialization code of main.c.

  • add header files

add in header file

  1.  #include "pikascript.h"

_images/130969048-4def9902-5f36-4798-9eac-ebbb1441087f.png

  • initialize pikaScript and get the pointer to the pikascript main object pikaMain

Add a startup code to the main function

  1. PikaObj* pikaMain = pikaScriptInit();

_images/130969274-ff2fdf6f-2389-466b-b51e-e7bc33472558.png

ended? Yes, it’s over, it’s that simple, isn’t it amazing.

This is because the precompiler does a lot of auxiliary work behind the scenes, including the automatic generation of the pikaScriptInit() function.

3.1.2.7. compile source code

When compiling the source code, you need to check the C99 standard, and the compilation optimization level can be selected arbitrarily, and pikascript supports it.

_images/130968626-7d8d4f46-eb0c-4ccd-9c34-eab160b290f5.png

Then you can compile it directly. Generally speaking, it can be passed directly.

You can use compiler version 5 or compiler version 6.

3.1.2.8. Contribute BSP

We sincerely appreciate your contribution, by contributing code, you can help PikaScript run on more platforms, and more developers will benefit from you.

Please see the operation method:

3.1.2.9. Add peripheral support

PikaScript manages peripherals through packages. To add peripheral support to the platform, please refer to the following documents: