Schoumi/microbit-dal
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Merge branch 'master' into flatstring

Browse source 
Conflicts:
	.gitignore
	inc/ErrorNo.h
	source/MicroBitDisplay.cpp
	source/MicroBitImage.cpp
This commit is contained in:
Michal Moskal 2015-11-12 16:13:45 -08:00
commit 56a560e5bc
44 changed files with 1557 additions and 746 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
.gitignore vendored
View file

@ -1,6 +1,6 @@
.yotta.json
build
*.swp
.yotta.json
yotta_modules
yotta_targets
*.swp
Makefile

44
inc/ErrorNo.h
View file

@ -3,25 +3,51 @@
/**
* Error codes used in the micro:bit runtime.
* These may be returned from functions implemented in the micro:bit runtime.
*/
enum Error{
// Invalid parameter given.
MICROBIT_INVALID_VALUE = -1,
enum ErrorCode{
// Invalid I/O operation requested.
MICROBIT_IO_OP_NA = -2,
// No error occurred.
MICROBIT_OK = 0,
// Invalid parameter given.
MICROBIT_INVALID_PARAMETER = -1001,
// Requested operation is unspupported.
MICROBIT_NOT_SUPPORTED = -1002,
// Device calibration errors
MICROBIT_COMPASS_IS_CALIBRATING = -3,
MICROBIT_COMPASS_CALIBRATE_REQUIRED = -4,
MICROBIT_CALIBRATION_IN_PROGRESS = -1003,
MICROBIT_CALIBRATION_REQUIRED = -1004,
// The requested operation could not be performed as the device has run out of some essential resource (e.g. allocated memory)
MICROBIT_NO_RESOURCES = -1005,
// The requested operation could not be performed as some essential resource is busy (e.g. the display)
MICROBIT_BUSY = -1006,
// The requested operation was cancelled before it completed.
MICROBIT_CANCELLED = -1007,
// I2C Communication error occured (typically I2C module on processor has locked up.)
MICROBIT_I2C_LOCKUP = 10,
MICROBIT_I2C_ERROR = -1010
};
/**
* Error codes used in the micro:bit runtime.
*/
enum PanicCode{
// PANIC Codes. These are not return codes, but are terminal conditions.
// These induce a panic operation, where all code stops executing, and a panic state is
// entered where the panic code is diplayed.
// Out out memory error. Heap storage was requested, but is not available.
MICROBIT_OOM = 20,
// Corruption detected in the micro:bit heap space
MICROBIT_HEAP_ERROR = 30
MICROBIT_HEAP_ERROR = 30,
// Dereference of a NULL pointer through the ManagedType class,
MICROBIT_NULL_DEREFERENCE = 40,
};
#endif

29
inc/ManagedType.h
View file

@ -11,7 +11,7 @@
template <class T>
class ManagedType
{
private:
protected:
int *ref;
@ -80,10 +80,37 @@ public:
*/
int getReferences();
/**
* De-reference operator overload. This makes modifying ref-counted POD
* easier.
*
* Example:
* @code
* ManagedType<int> x = 0;
* *x = 1; // mutates the ref-counted integer
*/
T& operator*() {
return *object;
}
/**
* Method call operator overload. This forwards the call to the underlying
* object.
*
* Example:
* @code
* ManagedType<T> x = new T();
* x->m(); // resolves to T::m
*/
T* operator->() {
if (object == NULL)
panic(MICROBIT_NULL_DEREFERENCE);
return object;
}
/**
* x.get() is shorthand for x.operator->()
*/
T* get() {
return object;
}

48
inc/MicroBit.h
View file

@ -32,7 +32,25 @@
#include "MicroBitFiber.h"
#include "MicroBitMessageBus.h"
/*
* The underlying Nordic libraries that support BLE do not compile cleanly with the stringent GCC settings we employ
* If we're compiling under GCC, then we suppress any warnings generated from this code (but not the rest of the DAL)
* The ARM cc compiler is more tolerant. We don't test __GNUC__ here to detect GCC as ARMCC also typically sets this
* as a compatability option, but does not support the options used...
*/
#if !defined (__arm)
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wunused-parameter"
#endif
#include "ble/BLE.h"
/*
* Return to our predefined compiler settings.
*/
#if !defined (__arm)
#pragma GCC diagnostic pop
#endif
#include "ble/services/DeviceInformationService.h"
#include "MicroBitDFUService.h"
#include "MicroBitEventService.h"
@ -62,10 +80,6 @@
#define MICROBIT_PIN_SDA P0_30
#define MICROBIT_PIN_SCL P0_0
#if CONFIG_ENABLED(MICROBIT_DBG)
extern Serial pc;
#endif
/**
* Class definition for a MicroBit device.
*
@ -90,9 +104,7 @@ class MicroBit
MicroBitI2C i2c;
// Serial Interface
#if CONFIG_DISABLED(MICROBIT_DBG)
MicroBitSerial serial;
#endif
// Array of components which are iterated during a system tick
MicroBitComponent* systemTickComponents[MICROBIT_SYSTEM_COMPONENTS];
@ -191,13 +203,14 @@ class MicroBit
* @note Values of 6 and below tend to lose resolution - do you really need to sleep for this short amount of time?
*
* @param milliseconds the amount of time, in ms, to wait for. This number cannot be negative.
* @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER milliseconds is less than zero.
*
* Example:
* @code
* uBit.sleep(20); //sleep for 20ms
* @endcode
*/
void sleep(int milliseconds);
int sleep(int milliseconds);
/**
* Generate a random number in the given range.
@ -205,7 +218,7 @@ class MicroBit
* TODO: Determine if we want to, given its relatively high power consumption!
*
* @param max the upper range to generate a number for. This number cannot be negative
* @return A random, natural number between 0 and the max-1. Or MICROBIT_INVALID_VALUE (defined in ErrorNo.h) if max is <= 0.
* @return A random, natural number between 0 and the max-1. Or MICROBIT_INVALID_PARAMETER if max is <= 0.
*
* Example:
* @code
@ -227,24 +240,33 @@ class MicroBit
/**
* add a component to the array of system components which invocate the systemTick member function during a systemTick
*
* @param component The component to add.
* @return MICROBIT_OK on success. MICROBIT_NO_RESOURCES is returned if further components cannot be supported.
*/
void addSystemComponent(MicroBitComponent *component);
int addSystemComponent(MicroBitComponent *component);
/**
* remove a component from the array of system components
* @param component The component to remove.
* @return MICROBIT_OK on success. MICROBIT_INVALID_PARAMETER is returned if the given component has not been previous added.
*/
void removeSystemComponent(MicroBitComponent *component);
int removeSystemComponent(MicroBitComponent *component);
/**
* add a component to the array of of idle thread components.
* isIdleCallbackNeeded is polled during a systemTick to determine if the idle thread should jump to the front of the queue
* @param component The component to add.
* @return MICROBIT_OK on success. MICROBIT_NO_RESOURCES is returned if further components cannot be supported.
*/
void addIdleComponent(MicroBitComponent *component);
int addIdleComponent(MicroBitComponent *component);
/**
* remove a component from the array of idle thread components
* @param component The component to remove.
* @return MICROBIT_OK on success. MICROBIT_INVALID_PARAMETER is returned if the given component has not been previous added.
*/
void removeIdleComponent(MicroBitComponent *component);
int removeIdleComponent(MicroBitComponent *component);
/**
* Determine the time since this MicroBit was last reset.
@ -260,7 +282,7 @@ class MicroBit
* @return A textual description of the currentlt executing micro:bit runtime.
* TODO: handle overflow case.
*/
char *systemVersion();
const char *systemVersion();
/**
* Triggers a microbit panic where an infinite loop will occur swapping between the panicFace and statusCode if provided.

24
inc/MicroBitAccelerometer.h
View file

@ -102,22 +102,27 @@ class MicroBitAccelerometer : public MicroBitComponent
* in this object. The nearest values are chosen to those defined
* that are supported by the hardware. The instance variables are then
* updated to reflect reality.
*
* @return MICROBIT_OK on success, MICROBIT_I2C_ERROR if the accelerometer could not be configured.
*/
void configure();
int configure();
/**
* Reads the acceleration data from the accelerometer, and stores it in our buffer.
* This is called by the tick() member function, if the interrupt is set!
* This is called by the tick() member function, if the interrupt is set.
*
* @return MICROBIT_OK on success, MICROBIT_I2C_ERROR is the read request fails.
*/
void update();
int update();
/**
* Attempts to set the sample rate of the accelerometer to the specified value (in ms).
* n.b. the requested rate may not be possible on the hardware. In this case, the
* nearest lower rate is chosen.
* @param period the requested time between samples, in milliseconds.
* @return MICROBIT_OK on success, MICROBIT_I2C_ERROR is the request fails.
*/
void setPeriod(int period);
int setPeriod(int period);
/**
* Reads the currently configured sample rate of the accelerometer.
@ -130,8 +135,9 @@ class MicroBitAccelerometer : public MicroBitComponent
* n.b. the requested range may not be possible on the hardware. In this case, the
* nearest lower rate is chosen.
* @param range The requested sample range of samples, in g.
* @return MICROBIT_OK on success, MICROBIT_I2C_ERROR is the request fails.
*/
void setRange(int range);
int setRange(int range);
/**
* Reads the currently configured sample range of the accelerometer.
@ -141,7 +147,7 @@ class MicroBitAccelerometer : public MicroBitComponent
/**
* Attempts to determine the 8 bit ID from the accelerometer.
* @return the 8 bit ID returned by the accelerometer
* @return the 8 bit ID returned by the accelerometer, or MICROBIT_I2C_ERROR if the request fails.
*
* Example:
* @code
@ -204,8 +210,9 @@ class MicroBitAccelerometer : public MicroBitComponent
*
* @param reg The address of the register to write to.
* @param value The value to write.
* @return MICROBIT_OK on success, MICROBIT_I2C_ERROR if the the write request failed.
*/
void writeCommand(uint8_t reg, uint8_t value);
int writeCommand(uint8_t reg, uint8_t value);
/**
* Issues a read command into the specified buffer.
@ -214,8 +221,9 @@ class MicroBitAccelerometer : public MicroBitComponent
* @param reg The address of the register to access.
* @param buffer Memory area to read the data into.
* @param length The number of bytes to read.
* @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER or MICROBIT_I2C_ERROR if the the read request failed.
*/
void readCommand(uint8_t reg, uint8_t* buffer, int length);
int readCommand(uint8_t reg, uint8_t* buffer, int length);
};
#endif

19
inc/MicroBitButton.h
View file

@ -31,6 +31,13 @@
#define MICROBIT_BUTTON_SIGMA_THRESH_LO 2
#define MICROBIT_BUTTON_DOUBLE_CLICK_THRESH 50
enum MicroBitButtonEventConfiguration
{
MICROBIT_BUTTON_SIMPLE_EVENTS,
MICROBIT_BUTTON_ALL_EVENTS
};
/**
* Class definition for MicroBit Button.
*
@ -38,12 +45,12 @@
*/
class MicroBitButton : public MicroBitComponent
{
PinName name; // mBed pin name of this pin.
DigitalIn pin; // The mBed object looking after this pin at any point in time (may change!).
PinName name; // mbed pin name of this pin.
DigitalIn pin; // The mbed object looking after this pin at any point in time (may change!).
unsigned long downStartTime; // used to store the current system clock when a button down event occurs
uint8_t sigma; // integration of samples over time.
uint8_t doubleClickTimer; // double click timer (ticks).
unsigned long downStartTime; // used to store the current system clock when a button down event occurs
uint8_t sigma; // integration of samples over time. We use this for debouncing, and noise tolerance for touch sensing
MicroBitButtonEventConfiguration eventConfiguration; // Do we want to generate high level event (clicks), or defer this to another service.
public:
@ -69,7 +76,7 @@ class MicroBitButton : public MicroBitComponent
* MICROBIT_BUTTON_EVT_HOLD
* @endcode
*/
MicroBitButton(uint16_t id, PinName name, PinMode mode = PullNone);
MicroBitButton(uint16_t id, PinName name, MicroBitButtonEventConfiguration eventConfiguration = MICROBIT_BUTTON_ALL_EVENTS, PinMode mode = PullNone);
/**
* Tests if this Button is currently pressed.

30
inc/MicroBitCompass.h
View file

@ -137,16 +137,18 @@ class MicroBitCompass : public MicroBitComponent
* in this object. The nearest values are chosen to those defined
* that are supported by the hardware. The instance variables are then
* updated to reflect reality.
* @return MICROBIT_OK or MICROBIT_I2C_ERROR if the magnetometer could not be configured.
*/
void configure();
int configure();
/**
* Attempts to set the sample rate of the compass to the specified value (in ms).
* n.b. the requested rate may not be possible on the hardware. In this case, the
* nearest lower rate is chosen.
* @param period the requested time between samples, in milliseconds.
* @return MICROBIT_OK or MICROBIT_I2C_ERROR if the magnetometer could not be updated.
*/
void setPeriod(int period);
int setPeriod(int period);
/**
* Reads the currently configured sample rate of the compass.
@ -156,7 +158,8 @@ class MicroBitCompass : public MicroBitComponent
/**
* Gets the current heading of the device, relative to magnetic north.
* @return the current heading, in degrees.
* @return the current heading, in degrees. Or MICROBIT_COMPASS_IS_CALIBRATING if the compass is calibrating.
* Or MICROBIT_COMPASS_CALIBRATE_REQUIRED if the compass requires calibration.
*
* Example:
* @code
@ -167,7 +170,7 @@ class MicroBitCompass : public MicroBitComponent
/**
* Attempts to determine the 8 bit ID from the magnetometer.
* @return the id of the compass (magnetometer)
* @return the id of the compass (magnetometer), or MICROBIT_I2C_ERROR if the magnetometer could not be updated.
*
* Example:
* @code
@ -211,13 +214,14 @@ class MicroBitCompass : public MicroBitComponent
/**
* Reads the currently die temperature of the compass.
* @return The temperature, in degrees celsius.
* @return the temperature in degrees celsius, or MICROBIT_I2C_ERROR if the magnetometer could not be updated.
*/
int readTemperature();
/**
* Perform the asynchronous calibration of the compass.
* This will fire MICROBIT_COMPASS_EVT_CAL_START and MICROBIT_COMPASS_EVT_CAL_END when finished.
* @return MICROBIT_OK, or MICROBIT_I2C_ERROR if the magnetometer could not be accessed.
* @note THIS MUST BE CALLED TO GAIN RELIABLE VALUES FROM THE COMPASS
*/
void calibrateAsync();
@ -227,7 +231,7 @@ class MicroBitCompass : public MicroBitComponent
* This will fire MICROBIT_COMPASS_EVT_CAL_START.
* @note THIS MUST BE CALLED TO GAIN RELIABLE VALUES FROM THE COMPASS
*/
void calibrateStart();
int calibrateStart();
/**
* Complete the calibration of the compass.
@ -270,8 +274,9 @@ class MicroBitCompass : public MicroBitComponent
*
* @param reg The address of the register to write to.
* @param value The value to write.
* @return MICROBIT_OK on success, MICROBIT_I2C_ERROR if the magnetometer could not be accessed.
*/
void writeCommand(uint8_t reg, uint8_t value);
int writeCommand(uint8_t reg, uint8_t value);
/**
* Issues a read command into the specified buffer.
@ -280,17 +285,18 @@ class MicroBitCompass : public MicroBitComponent
* @param reg The address of the register to access.
* @param buffer Memory area to read the data into.
* @param length The number of bytes to read.
* @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER or MICROBIT_I2C_ERROR if the magnetometer could not be accessed.
*/
void readCommand(uint8_t reg, uint8_t* buffer, int length);
int readCommand(uint8_t reg, uint8_t* buffer, int length);
/**
* Issues a read of a given address, and returns the value.
* Blocks the calling thread until complete.
*
* @param reg The based address of the 16 bit register to access.
* @return The register value, interpreted as a 16 but signed value.
* @return The register value, interpreted as a 16 but signed value, or MICROBIT_I2C_ERROR if the magnetometer could not be accessed.
*/
int16_t read16(uint8_t reg);
int read16(uint8_t reg);
/**
@ -298,9 +304,9 @@ class MicroBitCompass : public MicroBitComponent
* Blocks the calling thread until complete.
*
* @param reg The based address of the 16 bit register to access.
* @return The register value, interpreted as a 8 bi signed value.
* @return The register value, interpreted as a 8 bit unsigned value, or MICROBIT_I2C_ERROR if the magnetometer could not be accessed.
*/
uint8_t read8(uint8_t reg);
int read8(uint8_t reg);
};
#endif

64
inc/MicroBitCompat.h
View file

@ -5,67 +5,65 @@
#ifndef MICROBIT_COMPAT_H
#define MICROBIT_COMPAT_H
#include "ErrorNo.h"
#define PI 3.14159265359
/*! \
\brief Utility functions.
Included here often to reduce the need to import a whole library for simple opertations.
This helps to minimize our SRAM footprint.
*/
/*!
\brief returns the smallest of the two numbers
\param a the first number
\param b the number to compare against a
\return whichever value is the smallest
/**
* Determines the smallest of the two numbers
* @param a the first number
* @param b the second number
* @return The value of a or b that is the smallest
*/
inline int min(int a, int b)
{
return (a < b ? a : b);
}
/*!
\brief returns the biggest of the two numbers
\param a the first number
\param b the number to compare against a
\return whichever value is the biggest
/**
* Determines the largest of the two numbers
* @param a the first number
* @param b the second number
* @return The value of a or b that is the largest
*/
inline int max(int a, int b)
{
return (a > b ? a : b);
}
/*!
\brief clears b number of bytes given the pointer a
\param a the pointer to the beginning of the memory to clear
\param b the number of bytes to clear.
/**
* Sets a given area of memory to zero.
*
* @param a the pointer to the beginning of the memory to clear
* @param b the number of bytes to clear.
*/
inline void *memclr(void *a, size_t b)
{
return memset(a,0,b);
}
/*!
\brief returns true if the character c lies between ascii values 48 and 57 inclusive.
\param c the character to check
\return a bool, true if it is a digit, false otherwise
/**
* Determines if the given character is a printable ASCII/UTF8 decimal digit (0..9).
* @param c the character to check
* @return true if the character is a digit, false otherwise.
*/
inline bool isdigit(char c)
{
return (c > 47 && c < 58);
}
/*!
\brief Performs an in buffer reverse of a given char array
\param s the char* to reverse.
\return the reversed char*
/**
* Performs an in buffer reverse of a given char array
* @param s the string to reverse.
* @return MICROBIT_OK, or MICROBIT_INVALID_PARAMETER.
*/
void string_reverse(char *s);
int string_reverse(char *s);
/*!
\briefConverts a given integer into a base 10 ASCII equivalent.
\param n The number to convert.
\param s Pointer to a buffer in which to store the resulting string.
/**
* Converts a given integer into a string representation.
* @param n The number to convert.
* @param s A pointer to the buffer in which to store the resulting string.
* @return MICROBIT_OK, or MICROBIT_INVALID_PARAMETER.
*/
void itoa(int n, char *s);

4
inc/MicroBitComponent.h
View file

@ -42,7 +42,9 @@
#define MICROBIT_ID_IO_P20 25 //SDA
#define MICROBIT_ID_BUTTON_AB 26 // Button A+B multibutton
#define MICROBIT_ID_ALERT 27 // Alert channel, used for general purpose condition synchronisation and alerting.
#define MICROBIT_ID_NOTIFY 1023 // Notfication channel, for general purpose synchronisation
#define MICROBIT_ID_NOTIFY_ONE 1022 // Notfication channel, for general purpose synchronisation
class MicroBitComponent
{

9
inc/MicroBitConfig.h
View file

@ -88,9 +88,16 @@
// MESSAGE_BUS_LISTENER_NONBLOCKING
#ifndef MESSAGE_BUS_LISTENER_DEFAULT_FLAGS
#define MESSAGE_BUS_LISTENER_DEFAULT_FLAGS MESSAGE_BUS_LISTENER_REENTRANT
#define MESSAGE_BUS_LISTENER_DEFAULT_FLAGS MESSAGE_BUS_LISTENER_QUEUE_IF_BUSY
#endif
//
// Maximum event queue depth. If a queue exceeds this depth, further events will be dropped.
// Used to prevent message queues growing uncontrollably due to badly behaved user code and causing panic conditions.
//
#ifndef MESSAGE_BUS_LISTENER_MAX_QUEUE_DEPTH
#define MESSAGE_BUS_LISTENER_MAX_QUEUE_DEPTH 10
#endif
//
// Core micro:bit services
//

129
inc/MicroBitDisplay.h
View file

@ -1,14 +1,6 @@
#ifndef MICROBIT_DISPLAY_H
#define MICROBIT_DISPLAY_H
/**
* User definable constants
*/
#define MICROBIT_DISPLAY_ROTATION_0 0
#define MICROBIT_DISPLAY_ROTATION_90 1
#define MICROBIT_DISPLAY_ROTATION_180 2
#define MICROBIT_DISPLAY_ROTATION_270 3
/**
* Core Configuration settings.
@ -19,6 +11,7 @@
* MessageBus Event Codes
*/
#define MICROBIT_DISPLAY_EVT_ANIMATION_COMPLETE 1
#define MICROBIT_DISPLAY_EVT_FREE 2
/**
* I/O configurations for common devices.
@ -70,6 +63,7 @@
enum AnimationMode {
ANIMATION_MODE_NONE,
ANIMATION_MODE_STOPPED,
ANIMATION_MODE_SCROLL_TEXT,
ANIMATION_MODE_PRINT_TEXT,
ANIMATION_MODE_SCROLL_IMAGE,
@ -82,6 +76,13 @@ enum DisplayMode {
DISPLAY_MODE_GREYSCALE
};
enum DisplayRotation {
MICROBIT_DISPLAY_ROTATION_0,
MICROBIT_DISPLAY_ROTATION_90,
MICROBIT_DISPLAY_ROTATION_180,
MICROBIT_DISPLAY_ROTATION_270
};
struct MatrixPoint {
uint8_t x;
uint8_t y;
@ -103,7 +104,6 @@ class MicroBitDisplay : public MicroBitComponent
uint8_t mode;
uint8_t greyscaleBitMsk;
uint8_t timingCount;
uint16_t nonce;
Timeout renderTimer;
MicroBitFont font;
@ -115,10 +115,10 @@ class MicroBitDisplay : public MicroBitComponent
// The animation mode that's currently running (if any)
AnimationMode animationMode;
// The time (in ticks) between each frame update.
// The time in milliseconds between each frame update.
uint16_t animationDelay;
// The time (in ticks) since the frame update.
// The time in milliseconds since the frame update.
uint16_t animationTick;
// Stop playback of any animations
@ -221,6 +221,11 @@ class MicroBitDisplay : public MicroBitComponent
*/
void sendAnimationCompleteEvent();
/**
* Blocks the current fiber until the display is available (i.e. not effect is being displayed).
* Animations are queued until their time to display.
*/
void waitForFreeDisplay();
public:
// The mutable bitmap buffer being rendered to the LED matrix.
@ -242,42 +247,77 @@ public:
MicroBitDisplay(uint16_t id, uint8_t x, uint8_t y);
/**
* Resets the current given animation.
* @param delay the delay after which the animation is reset.
* Stops any currently running animation, and any that are waiting to be displayed.
*/
void resetAnimation(uint16_t delay);
void stopAnimation();
/**
* Frame update method, invoked periodically to strobe the display.
*/
virtual void systemTick();
/**
* Prints the given character to the display, if it is not in use.
*
* @param c The character to display.
* @param delay Optional parameter - the time for which to show the character. Zero displays the character forever.
* @return MICROBIT_OK, MICROBIT_BUSY is the screen is in use, or MICROBIT_INVALID_PARAMETER.
*
* Example:
* @code
* uBit.display.printAsync('p');
* uBit.display.printAsync('p',100);
* @endcode
*/
int printAsync(char c, int delay = 0);
/**
* Prints the given string to the display, one character at a time.
* Uses the given delay between characters.
* Returns immediately, and executes the animation asynchronously.
*
* @param s The string to display.
* @param delay The time to delay between characters, in timer ticks.
* @param delay The time to delay between characters, in milliseconds. Must be > 0.
* @return MICROBIT_OK, or MICROBIT_INVALID_PARAMETER.
*
* Example:
* @code
* uBit.display.printAsync("abc123",400);
* @endcode
*/
void printAsync(ManagedString s, int delay = MICROBIT_DEFAULT_PRINT_SPEED);
int printAsync(ManagedString s, int delay = MICROBIT_DEFAULT_PRINT_SPEED);
/**
* Prints the given image to the display, if the display is not in use.
* Returns immediately, and executes the animation asynchronously.
*
* @param i The image to display.
* @param x The horizontal position on the screen to display the image (default 0)
* @param y The vertical position on the screen to display the image (default 0)
* @param alpha Treats the brightness level '0' as transparent (default 0)
* @param delay The time to delay between characters, in milliseconds. set to 0 to display forever. (default 0).
*
* Example:
* @code
* MicrobitImage i("1,1,1,1,1\n1,1,1,1,1\n");
* uBit.display.print(i,400);
* @endcode
*/
int printAsync(MicroBitImage i, int x, int y, int alpha, int delay = 0);
/**
* Prints the given character to the display.
*
* @param c The character to display.
* @param delay The time to delay between characters, in milliseconds. Must be > 0.
* @return MICROBIT_OK, MICROBIT_CANCELLED or MICROBIT_INVALID_PARAMETER.
*
* Example:
* @code
* uBit.display.print('p');
* @endcode
*/
void print(char c, int delay = 0);
int print(char c, int delay = 0);
/**
* Prints the given string to the display, one character at a time.
@ -285,21 +325,23 @@ public:
* Blocks the calling thread until all the text has been displayed.
*
* @param s The string to display.
* @param delay The time to delay between characters, in timer ticks.
* @param delay The time to delay between characters, in milliseconds. Must be > 0.
* @return MICROBIT_OK, MICROBIT_CANCELLED or MICROBIT_INVALID_PARAMETER.
*
* Example:
* @code
* uBit.display.print("abc123",400);
* @endcode
*/
void print(ManagedString s, int delay = MICROBIT_DEFAULT_PRINT_SPEED);
int print(ManagedString s, int delay = MICROBIT_DEFAULT_PRINT_SPEED);
/**
* Prints the given image to the display.
* Blocks the calling thread until all the text has been displayed.
*
* @param i The image to display.
* @param delay The time to delay between characters, in timer ticks.
* @param delay The time to display the image for, or zero to show the image forever. Must be >= 0.
* @return MICROBIT_OK, MICROBIT_BUSY if the display is already in use, or MICROBIT_INVALID_PARAMETER.
*
* Example:
* @code
@ -307,7 +349,7 @@ public:
* uBit.display.print(i,400);
* @endcode
*/
void print(MicroBitImage i, int x, int y, int alpha, int delay = MICROBIT_DEFAULT_PRINT_SPEED);
int print(MicroBitImage i, int x, int y, int alpha, int delay = 0);
/**
* Scrolls the given string to the display, from right to left.
@ -315,21 +357,24 @@ public:
* Returns immediately, and executes the animation asynchronously.
*
* @param s The string to display.
* @param delay The time to delay between characters, in timer ticks.
* @param delay The time to delay between each update to the display, in milliseconds. Must be > 0.
* @return MICROBIT_OK, MICROBIT_BUSY if the display is already in use, or MICROBIT_INVALID_PARAMETER.
*
* Example:
* @code
* uBit.display.scrollAsync("abc123",100);
* @endcode
*/
void scrollAsync(ManagedString s, int delay = MICROBIT_DEFAULT_SCROLL_SPEED);
int scrollAsync(ManagedString s, int delay = MICROBIT_DEFAULT_SCROLL_SPEED);
/**
* Scrolls the given image across the display, from right to left.
* Returns immediately, and executes the animation asynchronously.
*
* @param image The image to display.
* @param delay The time to delay between each scroll update, in timer ticks. Has a default.
* @param stride The number of pixels to move in each quantum. Has a default.
* @param delay The time to delay between each update to the display, in milliseconds. Must be > 0.
* @param stride The number of pixels to move in each update. Default value is the screen width.
* @return MICROBIT_OK, MICROBIT_BUSY if the display is already in use, or MICROBIT_INVALID_PARAMETER.
*
* Example:
* @code
@ -337,7 +382,7 @@ public:
* uBit.display.scrollAsync(i,100,1);
* @endcode
*/
void scrollAsync(MicroBitImage image, int delay = MICROBIT_DEFAULT_SCROLL_SPEED, int stride = MICROBIT_DEFAULT_SCROLL_STRIDE);
int scrollAsync(MicroBitImage image, int delay = MICROBIT_DEFAULT_SCROLL_SPEED, int stride = MICROBIT_DEFAULT_SCROLL_STRIDE);
/**
* Scrolls the given string to the display, from right to left.
@ -345,22 +390,24 @@ public:
* Blocks the calling thread until all the text has been displayed.
*
* @param s The string to display.
* @param delay The time to delay between characters, in timer ticks.
* @param delay The time to delay between each update to the display, in milliseconds. Must be > 0.
* @return MICROBIT_OK, MICROBIT_CANCELLED or MICROBIT_INVALID_PARAMETER.
*
* Example:
* @code
* uBit.display.scroll("abc123",100);
* @endcode
*/
void scroll(ManagedString s, int delay = MICROBIT_DEFAULT_SCROLL_SPEED);
int scroll(ManagedString s, int delay = MICROBIT_DEFAULT_SCROLL_SPEED);
/**
* Scrolls the given image across the display, from right to left.
* Blocks the calling thread until all the text has been displayed.
*
* @param image The image to display.
* @param delay The time to delay between each scroll update, in timer ticks. Has a default.
* @param stride The number of pixels to move in each quantum. Has a default.
* @param delay The time to delay between each update to the display, in milliseconds. Must be > 0.
* @param stride The number of pixels to move in each update. Default value is the screen width.
* @return MICROBIT_OK, MICROBIT_CANCELLED or MICROBIT_INVALID_PARAMETER.
*
* Example:
* @code
@ -368,15 +415,16 @@ public:
* uBit.display.scroll(i,100,1);
* @endcode
*/
void scroll(MicroBitImage image, int delay = MICROBIT_DEFAULT_SCROLL_SPEED, int stride = MICROBIT_DEFAULT_SCROLL_STRIDE);
int scroll(MicroBitImage image, int delay = MICROBIT_DEFAULT_SCROLL_SPEED, int stride = MICROBIT_DEFAULT_SCROLL_STRIDE);
/**
* "Animates" the current image across the display with a given stride, finishing on the last frame of the animation.
* Returns immediately.
*
* @param image The image to display.
* @param delay The time to delay between each animation update, in timer ticks. Has a default.
* @param stride The number of pixels to move in each quantum. Has a default.
* @param delay The time to delay between each update to the display, in milliseconds. Must be > 0.
* @param stride The number of pixels to move in each update. Default value is the screen width.
* @return MICROBIT_OK, MICROBIT_BUSY if the screen is in use, or MICROBIT_INVALID_PARAMETER.
*
* Example:
* @code
@ -388,15 +436,16 @@ public:
* uBit.display.animateAsync(i,100,5);
* @endcode
*/
void animateAsync(MicroBitImage image, int delay, int stride, int startingPosition = MICROBIT_DISPLAY_ANIMATE_DEFAULT_POS);
int animateAsync(MicroBitImage image, int delay, int stride, int startingPosition = MICROBIT_DISPLAY_ANIMATE_DEFAULT_POS);
/**
* "Animates" the current image across the display with a given stride, finishing on the last frame of the animation.
* Blocks the calling thread until the animation is complete.
*
* @param image The image to display.
* @param delay The time to delay between each animation update, in timer ticks. Has a default.
* @param stride The number of pixels to move in each quantum. Has a default.
* @param delay The time to delay between each update to the display, in milliseconds. Must be > 0.
* @param stride The number of pixels to move in each update. Default value is the screen width.
* @return MICROBIT_OK, MICROBIT_CANCELLED or MICROBIT_INVALID_PARAMETER.
*
* Example:
* @code
@ -408,19 +457,19 @@ public:
* uBit.display.animate(i,100,5);
* @endcode
*/
void animate(MicroBitImage image, int delay, int stride, int startingPosition = MICROBIT_DISPLAY_ANIMATE_DEFAULT_POS);
int animate(MicroBitImage image, int delay, int stride, int startingPosition = MICROBIT_DISPLAY_ANIMATE_DEFAULT_POS);
/**
* Sets the display brightness to the specified level.
* @param b The brightness to set the brightness to, in the range 0..255.
* @return MICROBIT_OK, or MICROBIT_INVALID_PARAMETER
*
* Example:
* @code
* uBit.display.setBrightness(255); //max brightness
* @endcode
*/
void setBrightness(int b);
int setBrightness(int b);
/**
* Sets the mode of the display.
@ -453,7 +502,7 @@ public:
* uBit.display.rotateTo(MICROBIT_DISPLAY_ROTATION_180); //rotates 180 degrees from original orientation
* @endcode
*/
void rotateTo(uint8_t position);
void rotateTo(DisplayRotation position);
/**
* Enables the display, should only be called if the display is disabled.

8
inc/MicroBitFiber.h
View file

@ -170,8 +170,9 @@ void fiber_wait_for_event(uint16_t id, uint16_t value);
* We only create an additional fiber if that function performs a block operation.
*
* @param entry_fn The function to execute.
* @return MICROBIT_OK, or MICROBIT_INVALID_PARAMETER.
*/
void invoke(void (*entry_fn)(void));
int invoke(void (*entry_fn)(void));
/**
* Executes the given function asynchronously if necessary.
@ -183,9 +184,10 @@ void invoke(void (*entry_fn)(void));
* We only create an additional fiber if that function performs a block operation.
*
* @param entry_fn The function to execute.
* @param param an untyped parameter passed into the entry_fn anf completion_fn.
* @param param an untyped parameter passed into the entry_fn and completion_fn.
* @return MICROBIT_OK, or MICROBIT_INVALID_PARAMETER.
*/
void invoke(void (*entry_fn)(void *), void *param);
int invoke(void (*entry_fn)(void *), void *param);
/**
* Resizes the stack allocation of the current fiber if necessary to hold the system stack.

21
inc/MicroBitHeapAllocator.h
View file

@ -35,8 +35,29 @@
// Flag to indicate that a given block is FREE/USED
#define MICROBIT_HEAP_BLOCK_FREE 0x80000000
/**
* Initialise the microbit heap according to the parameters defined in MicroBitConfig.h
* After this is called, any future calls to malloc, new, free or delete will use the new heap.
* n.b. only code that #includes MicroBitHeapAllocator.h will use this heap. This includes all micro:bit runtime
* code, and user code targetting the runtime. External code can choose to include this file, or
* simply use the standard mbed heap.
*
* @return MICROBIT_OK on success, or MICROBIT_NO_RESOURCES if the heap could not be allocted.
*/
int microbit_heap_init();
/**
* Attempt to allocate a given amount of memory from any of our configured heap areas.
* @param size The amount of memory, in bytes, to allocate.
* @return A pointer to the allocated memory, or NULL if insufficient memory is available.
*/
void *microbit_malloc(size_t size);
/**
* Release a given area of memory from the heap.
* @param mem The memory area to release.
*/
void microbit_free(void *mem);
/*

28
inc/MicroBitI2C.h
View file

@ -8,11 +8,11 @@
/**
* Class definition for MicroBitI2C.
*
* Represents a wrapped mbed call to hopefully fix silicon issues once and for all.
* Presents a wrapped mbed call to capture failed I2C operations caused by a known silicon bug in the nrf51822.
* Attempts to automatically reset and restart the I2C hardware if this case is detected.
*/
class MicroBitI2C : public I2C
{
uint8_t retries;
public:
@ -29,9 +29,29 @@ class MicroBitI2C : public I2C
* @note this should prevent i2c lockups as well.
*/
MicroBitI2C(PinName sda, PinName scl);
/**
* Performs a complete read transaction. The bottom bit of the address is forced to 1 to indicate a read.
*
* @address 8-bit I2C slave address [ addr | 1 ]
* @data Pointer to the byte-array to read data in to
* @length Number of bytes to read
* @repeated Repeated start, true - don't send stop at end.
*
* @return MICROBIT_OK on success, MICROBIT_I2C_ERROR if an unresolved read failure is detected.
*/
int read(int address, char *data, int length, bool repeated = false);
/**
* Performs a complete write transaction. The bottom bit of the address is forced to 0 to indicate a write.
*
* @address 8-bit I2C slave address [ addr | 0 ]
* @data Pointer to the byte-arraycontaining the data to write
* @length Number of bytes to write
* @repeated Repeated start, true - don't send stop at end.
*
* @return MICROBIT_OK on success, MICROBIT_I2C_ERROR if an unresolved write failure is detected.
*/
int write(int address, const char *data, int length, bool repeated = false);
};

34
inc/MicroBitImage.h
View file

@ -206,6 +206,7 @@ class MicroBitImage
* @param x The co-ordinate of the pixel to change w.r.t. top left origin.
* @param y The co-ordinate of the pixel to change w.r.t. top left origin.
* @param value The new value of the pixel (the brightness level 0-255)
* @return MICROBIT_OK, or MICROBIT_INVALID_PARAMETER.
*
* Example:
* @code
@ -213,11 +214,14 @@ class MicroBitImage
* i.setPixelValue(0,0,255);
* @endcode
*/
void setPixelValue(int16_t x , int16_t y, uint8_t value);
int setPixelValue(int16_t x , int16_t y, uint8_t value);
/**
* Determines the value of a given pixel.
* @return The value assigned to the given pixel location (the brightness level 0-255)
* Determines the value of a given pixel.
*
* @param x The x co-ordinate of the pixel to read. Must be within the dimensions of the image.
* @param y The y co-ordinate of the pixel to read. Must be within the dimensions of the image.
* @return The value assigned to the given pixel location (the brightness level 0-255), or MICROBIT_INVALID_PARAMETER.
*
* Example:
* @code
@ -232,9 +236,10 @@ class MicroBitImage
* 2D array representing the image.
* Origin is in the top left corner of the image.
*
* @param x the width of the image.
* @param y the height of the image.
* @param x the width of the image. Must be within the dimensions of the image.
* @param y the width of the image. Must be within the dimensions of the image.
* @param bitmap a 2D array representing the image.
* @return MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER.
*
* Example:
* @code
@ -243,7 +248,7 @@ class MicroBitImage
* i.printImage(0,0,heart);
* @endcode
*/
void printImage(int16_t x, int16_t y, const uint8_t *bitmap);
int printImage(int16_t x, int16_t y, const uint8_t *bitmap);
/**
* Pastes a given bitmap at the given co-ordinates.
@ -253,7 +258,7 @@ class MicroBitImage
* @param x The leftmost X co-ordinate in this image where the given image should be pasted.
* @param y The uppermost Y co-ordinate in this image where the given image should be pasted.
* @param alpha set to 1 if transparency clear pixels in given image should be treated as transparent. Set to 0 otherwise.
* @return The number of pixels written.
* @return The number of pixels written, or MICROBIT_INVALID_PARAMETER.
*
* Example:
* @code
@ -270,6 +275,7 @@ class MicroBitImage
* @param c The character to display.
* @param x The x co-ordinate of on the image to place the top left of the character
* @param y The y co-ordinate of on the image to place the top left of the character
* @return MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER.
*
* Example:
* @code
@ -277,12 +283,13 @@ class MicroBitImage
* i.print('a',0,0);
* @endcode
*/
void print(char c, int16_t x, int16_t y);
int print(char c, int16_t x, int16_t y);
/**
* Shifts the pixels in this Image a given number of pixels to the Left.
*
* @param n The number of pixels to shift.
* @return MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER.
*
* Example:
* @code
@ -291,12 +298,13 @@ class MicroBitImage
* i.shiftLeft(5); //displays a small heart :)
* @endcode
*/
void shiftLeft(int16_t n);
int shiftLeft(int16_t n);
/**
* Shifts the pixels in this Image a given number of pixels to the Right.
*
* @param n The number of pixels to shift.
* @return MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER.
*
* Example:
* @code
@ -306,12 +314,13 @@ class MicroBitImage
* i.shiftRight(5); //displays a big heart :)
* @endcode
*/
void shiftRight(int16_t n);
int shiftRight(int16_t n);
/**
* Shifts the pixels in this Image a given number of pixels to Upward.
*
* @param n The number of pixels to shift.
* @return MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER.
*
* Example:
* @code
@ -320,12 +329,13 @@ class MicroBitImage
* i.shiftUp(1);
* @endcode
*/
void shiftUp(int16_t n);
int shiftUp(int16_t n);
/**
* Shifts the pixels in this Image a given number of pixels to Downward.
*
* @param n The number of pixels to shift.
* @return MICROBIT_OK on success, or MICROBIT_INVALID_PARAMETER.
*
* Example:
* @code
@ -334,7 +344,7 @@ class MicroBitImage
* i.shiftDown(1);
* @endcode
*/
void shiftDown(int16_t n);
int shiftDown(int16_t n);
/**
* Gets the width of this image.

2
inc/MicroBitListener.h
View file

@ -14,6 +14,8 @@
#define MESSAGE_BUS_LISTENER_DROP_IF_BUSY 0x0020
#define MESSAGE_BUS_LISTENER_NONBLOCKING 0x0040
#define MESSAGE_BUS_LISTENER_URGENT 0x0080
#define MESSAGE_BUS_LISTENER_DELETING 0x8000
#define MESSAGE_BUS_LISTENER_IMMEDIATE (MESSAGE_BUS_LISTENER_NONBLOCKING | MESSAGE_BUS_LISTENER_URGENT)

77
inc/MicroBitMessageBus.h
View file

@ -64,10 +64,11 @@ class MicroBitMessageBus : public MicroBitComponent
* or the constructors provided by MicroBitEvent.
*
* @param evt The event to send.
* @param mask The type of listeners to process (optional). Matches MicroBitListener flags. If not defined, all standard listeners will be processed.
* @return The 1 if all matching listeners were processed, 0 if further processing is required.
* @param urgent The type of listeners to process (optional). If set to true, only listeners defined as urgent and non-blocking will be processed
* otherwise, all other (standard) listeners will be processed.
* @return 1 if all matching listeners were processed, 0 if further processing is required.
*/
int process(MicroBitEvent &evt, uint32_t mask = MESSAGE_BUS_LISTENER_REENTRANT | MESSAGE_BUS_LISTENER_QUEUE_IF_BUSY | MESSAGE_BUS_LISTENER_DROP_IF_BUSY | MESSAGE_BUS_LISTENER_NONBLOCKING);
int process(MicroBitEvent &evt, bool urgent = false);
/**
* Register a listener function.
@ -78,7 +79,9 @@ class MicroBitMessageBus : public MicroBitComponent
* @param value The value of messages to listen for. Events with any other values will be filtered.
* Use MICROBIT_EVT_ANY to receive events of any value.
*
* @param hander The function to call when an event is received.
* @param handler The function to call when an event is received.
*
* @return MICROBIT_OK on success MICROBIT_INVALID_PARAMETER
*
* Example:
* @code
@ -89,7 +92,7 @@ class MicroBitMessageBus : public MicroBitComponent
* uBit.MessageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick); // call function when ever a click event is detected.
* @endcode
*/
void listen(int id, int value, void (*handler)(MicroBitEvent), uint16_t flags = MESSAGE_BUS_LISTENER_DEFAULT_FLAGS);
int listen(int id, int value, void (*handler)(MicroBitEvent), uint16_t flags = MESSAGE_BUS_LISTENER_DEFAULT_FLAGS);
/**
* Register a listener function.
@ -101,6 +104,8 @@ class MicroBitMessageBus : public MicroBitComponent
* Use MICROBIT_EVT_ANY to receive events of any value.
*
* @param hander The function to call when an event is received.
*
* @return MICROBIT_OK on success MICROBIT_INVALID_PARAMETER
*
* Example:
* @code
@ -111,7 +116,7 @@ class MicroBitMessageBus : public MicroBitComponent
* uBit.MessageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButtonBClick); // call function when ever a click event is detected.
* @endcode