MicroBitConfig.h

00001 /*
00002 The MIT License (MIT)
00003 
00004 Copyright (c) 2016 British Broadcasting Corporation.
00005 This software is provided by Lancaster University by arrangement with the BBC.
00006 
00007 Permission is hereby granted, free of charge, to any person obtaining a
00008 copy of this software and associated documentation files (the "Software"),
00009 to deal in the Software without restriction, including without limitation
00010 the rights to use, copy, modify, merge, publish, distribute, sublicense,
00011 and/or sell copies of the Software, and to permit persons to whom the
00012 Software is furnished to do so, subject to the following conditions:
00013 
00014 The above copyright notice and this permission notice shall be included in
00015 all copies or substantial portions of the Software.
00016 
00017 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00018 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00019 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
00020 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00021 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
00022 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
00023 DEALINGS IN THE SOFTWARE.
00024 */
00025 
00026 /**
00027   * Compile time configuration options for the micro:bit runtime.
00028   */
00029 
00030 #ifndef MICROBIT_CONFIG_H
00031 #define MICROBIT_CONFIG_H
00032 
00033 #include "mbed.h"
00034 
00035 //
00036 // Memory configuration
00037 //
00038 
00039 // The start address of usable RAM memory.
00040 #ifndef MICROBIT_SRAM_BASE
00041 #define MICROBIT_SRAM_BASE                      0x20000008
00042 #endif
00043 
00044 // Physical address of the top of SRAM.
00045 #ifndef MICROBIT_SRAM_END
00046 #define MICROBIT_SRAM_END                       0x20004000
00047 #endif
00048 
00049 // The end address of memory normally reserved for Soft Device.
00050 #ifndef MICROBIT_SD_LIMIT
00051 #define MICROBIT_SD_LIMIT                       0x20002000
00052 #endif
00053 
00054 // The physical address in memory of the Soft Device GATT table.
00055 #ifndef MICROBIT_SD_GATT_TABLE_START
00056 #define MICROBIT_SD_GATT_TABLE_START            0x20001900
00057 #endif
00058 
00059 // Physical address of the top of the system stack (on mbed-classic this is the top of SRAM)
00060 #ifndef CORTEX_M0_STACK_BASE
00061 #define CORTEX_M0_STACK_BASE                    MICROBIT_SRAM_END
00062 #endif
00063 
00064 // Amount of memory reserved for the stack at the end of memory (bytes).
00065 #ifndef MICROBIT_STACK_SIZE
00066 #define MICROBIT_STACK_SIZE                     2048
00067 #endif
00068 
00069 // Physical address of the end of mbed heap space.
00070 #ifndef MICROBIT_HEAP_END
00071 #define MICROBIT_HEAP_END                       (CORTEX_M0_STACK_BASE - MICROBIT_STACK_SIZE)
00072 #endif
00073 
00074 // Enables or disables the MicroBitHeapllocator. Note that if disabled, no reuse of the SRAM normally
00075 // reserved for SoftDevice is possible, and out of memory condition will no longer be trapped...
00076 // i.e. panic() will no longer be triggered on memory full conditions.
00077 #ifndef MICROBIT_HEAP_ALLOCATOR
00078 #define MICROBIT_HEAP_ALLOCATOR                 1
00079 #endif
00080 
00081 // Block size used by the allocator in bytes.
00082 // n.b. Currently only 32 bits (4 bytes) is supported.
00083 #ifndef MICROBIT_HEAP_BLOCK_SIZE
00084 #define MICROBIT_HEAP_BLOCK_SIZE                4
00085 #endif
00086 
00087 // The proportion of SRAM available on the mbed heap to reserve for the micro:bit heap.
00088 #ifndef MICROBIT_NESTED_HEAP_SIZE
00089 #define MICROBIT_NESTED_HEAP_SIZE               0.75
00090 #endif
00091 
00092 // If defined, reuse any unused SRAM normally reserved for SoftDevice (Nordic's memory resident BLE stack) as heap memory.
00093 // The amount of memory reused depends upon whether or not BLE is enabled using MICROBIT_BLE_ENABLED.
00094 // Set '1' to enable.
00095 #ifndef MICROBIT_HEAP_REUSE_SD
00096 #define MICROBIT_HEAP_REUSE_SD                  1
00097 #endif
00098 
00099 // The amount of memory allocated to Soft Device to hold its BLE GATT table.
00100 // For standard S110 builds, this should be word aligned and in the range 0x300 - 0x700.
00101 // Any unused memory will be automatically reclaimed as HEAP memory if both MICROBIT_HEAP_REUSE_SD and MICROBIT_HEAP_ALLOCATOR are enabled.
00102 #ifndef MICROBIT_SD_GATT_TABLE_SIZE
00103 #define MICROBIT_SD_GATT_TABLE_SIZE             0x700
00104 #endif
00105 
00106 //
00107 // Fiber scheduler configuration
00108 //
00109 
00110 // Scheduling quantum (milliseconds)
00111 // Also used to drive the micro:bit runtime system ticker.
00112 #ifndef SYSTEM_TICK_PERIOD_MS
00113 #define SYSTEM_TICK_PERIOD_MS                   6
00114 #endif
00115 
00116 //
00117 // Message Bus:
00118 // Default behaviour for event handlers, if not specified in the listen() call
00119 //
00120 // Permissable values are:
00121 //   MESSAGE_BUS_LISTENER_REENTRANT
00122 //   MESSAGE_BUS_LISTENER_QUEUE_IF_BUSY
00123 //   MESSAGE_BUS_LISTENER_DROP_IF_BUSY
00124 //   MESSAGE_BUS_LISTENER_IMMEDIATE
00125 
00126 #ifndef EVENT_LISTENER_DEFAULT_FLAGS
00127 #define EVENT_LISTENER_DEFAULT_FLAGS            MESSAGE_BUS_LISTENER_QUEUE_IF_BUSY
00128 #endif
00129 
00130 //
00131 // Maximum event queue depth. If a queue exceeds this depth, further events will be dropped.
00132 // Used to prevent message queues growing uncontrollably due to badly behaved user code and causing panic conditions.
00133 //
00134 #ifndef MESSAGE_BUS_LISTENER_MAX_QUEUE_DEPTH
00135 #define MESSAGE_BUS_LISTENER_MAX_QUEUE_DEPTH    10
00136 #endif
00137 
00138 //
00139 // Core micro:bit services
00140 //
00141 
00142 // To reduce memory cost and complexity, the micro:bit allows components to register for
00143 // periodic callback events during interrupt context, which occur every scheduling quantum (FIBER_TICK_PERIOD_MS)
00144 // This defines the maximum size of interrupt callback list.
00145 #ifndef MICROBIT_SYSTEM_COMPONENTS
00146 #define MICROBIT_SYSTEM_COMPONENTS              10
00147 #endif
00148 
00149 // To reduce memory cost and complexity, the micro:bit allows components to register for
00150 // periodic callback events when the processor is idle.
00151 // This defines the maximum size of the idle callback list.
00152 #ifndef MICROBIT_IDLE_COMPONENTS
00153 #define MICROBIT_IDLE_COMPONENTS                6
00154 #endif
00155 
00156 //
00157 // BLE options
00158 //
00159 // The BLE stack is very memory hungry. Each service can therefore be compiled in or out
00160 // by enabling/disabling the options below.
00161 //
00162 // n.b. The minimum set of services to enable over the air programming of the device will
00163 // still be brought up in pairing mode regardless of the settings below.
00164 //
00165 
00166 // Enable/Disable BLE during normal operation.
00167 // Set '1' to enable.
00168 #ifndef MICROBIT_BLE_ENABLED
00169 #define MICROBIT_BLE_ENABLED                    1
00170 #endif
00171 
00172 // Enable/Disable BLE pairing mode mode at power up.
00173 // Set '1' to enable.
00174 #ifndef MICROBIT_BLE_PAIRING_MODE
00175 #define MICROBIT_BLE_PAIRING_MODE               0
00176 #endif
00177 
00178 // Enable/Disable the use of private resolvable addresses.
00179 // Set '1' to enable.
00180 // n.b. This is known to be a feature that suffers compatibility issues with many BLE central devices.
00181 #ifndef MICROBIT_BLE_PRIVATE_ADDRESSES
00182 #define MICROBIT_BLE_PRIVATE_ADDRESSES          0
00183 #endif
00184 
00185 // Convenience option to enable / disable BLE security entirely
00186 // Open BLE links are not secure, but commonly used during the development of BLE services
00187 // Set '1' to disable all secuity
00188 #ifndef MICROBIT_BLE_OPEN
00189 #define MICROBIT_BLE_OPEN                       1
00190 #endif
00191 
00192 // Configure for open BLE operation if so configured
00193 #if (MICROBIT_BLE_OPEN == 1)
00194 #define MICROBIT_BLE_SECURITY_LEVEL             SECURITY_MODE_ENCRYPTION_OPEN_LINK
00195 #define MICROBIT_BLE_WHITELIST                  0
00196 #define MICROBIT_BLE_ADVERTISING_TIMEOUT        0
00197 #define MICROBIT_BLE_DEFAULT_TX_POWER           6
00198 #endif
00199 
00200 
00201 // Define the default, global BLE security requirements for MicroBit BLE services
00202 // May be one of the following options (see mbed's SecurityManager class implementaiton detail)
00203 // SECURITY_MODE_ENCRYPTION_OPEN_LINK:      No bonding, encryption, or whitelisting required.
00204 // SECURITY_MODE_ENCRYPTION_NO_MITM:        Bonding, encyption and whitelisting but no passkey.
00205 // SECURITY_MODE_ENCRYPTION_WITH_MITM:      Bonding, encrytion and whitelisting with passkey authentication.
00206 //
00207 #ifndef MICROBIT_BLE_SECURITY_LEVEL
00208 #define MICROBIT_BLE_SECURITY_LEVEL             SECURITY_MODE_ENCRYPTION_OPEN_LINK
00209 #endif
00210 
00211 // Enable/Disable the use of BLE whitelisting.
00212 // If enabled, the micro:bit will only respond to connection requests from
00213 // known, bonded devices.
00214 #ifndef MICROBIT_BLE_WHITELIST
00215 #define MICROBIT_BLE_WHITELIST                  1
00216 #endif
00217 
00218 // Define the period of time for which the BLE stack will advertise (seconds)
00219 // Afer this period, advertising will cease. Set to '0' for no timeout (always advertise).
00220 #ifndef MICROBIT_BLE_ADVERTISING_TIMEOUT
00221 #define MICROBIT_BLE_ADVERTISING_TIMEOUT        0
00222 #endif
00223 
00224 // Defines default power level of the BLE radio transmitter.
00225 // Valid values are in the range 0..7 inclusive, with 0 being the lowest power and 7 the highest power.
00226 // Based on trials undertaken by the BBC, the radio is normally set to its lowest power level
00227 // to best protect children's privacy.
00228 #ifndef MICROBIT_BLE_DEFAULT_TX_POWER
00229 #define MICROBIT_BLE_DEFAULT_TX_POWER           6
00230 #endif
00231 
00232 // Enable/Disable BLE Service: MicroBitDFU
00233 // This allows over the air programming during normal operation.
00234 // Set '1' to enable.
00235 #ifndef MICROBIT_BLE_DFU_SERVICE
00236 #define MICROBIT_BLE_DFU_SERVICE                1
00237 #endif
00238 
00239 // Enable/Disable BLE Service: MicroBitEventService
00240 // This allows routing of events from the micro:bit message bus over BLE.
00241 // Set '1' to enable.
00242 #ifndef MICROBIT_BLE_EVENT_SERVICE
00243 #define MICROBIT_BLE_EVENT_SERVICE              1
00244 #endif
00245 
00246 // Enable/Disable BLE Service: MicroBitDeviceInformationService
00247 // This enables the standard BLE device information service.
00248 // Set '1' to enable.
00249 #ifndef MICROBIT_BLE_DEVICE_INFORMATION_SERVICE
00250 #define MICROBIT_BLE_DEVICE_INFORMATION_SERVICE 1
00251 #endif
00252 
00253 //
00254 // Accelerometer options
00255 //
00256 
00257 // Enable this to read 10 bits of data from the acclerometer.
00258 // Otherwise, 8 bits are used.
00259 // Set '1' to enable.
00260 #ifndef USE_ACCEL_LSB
00261 #define USE_ACCEL_LSB                           0
00262 #endif
00263 
00264 //
00265 // Display options
00266 //
00267 
00268 // Selects the matrix configuration for the display driver.
00269 // Known, acceptable options are:
00270 //
00271 #define MICROBUG_REFERENCE_DEVICE               1
00272 #define MICROBIT_3X9                            2
00273 #define MICROBIT_SB1                            3
00274 #define MICROBIT_SB2                            4
00275 
00276 #ifndef MICROBIT_DISPLAY_TYPE
00277 #define MICROBIT_DISPLAY_TYPE                   MICROBIT_SB2
00278 #endif
00279 
00280 // Selects the minimum permissable brightness level for the device
00281 // in the region of 0 (off) to 255 (full brightness)
00282 #ifndef MICROBIT_DISPLAY_MINIMUM_BRIGHTNESS
00283 #define MICROBIT_DISPLAY_MINIMUM_BRIGHTNESS     1
00284 #endif
00285 
00286 // Selects the maximum permissable brightness level for the device
00287 // in the region of 0 (off) to 255 (full brightness)
00288 #ifndef MICROBIT_DISPLAY_MAXIMUM_BRIGHTNESS
00289 #define MICROBIT_DISPLAY_MAXIMUM_BRIGHTNESS     255
00290 #endif
00291 
00292 // Selects the default brightness for the display
00293 // in the region of zero (off) to 255 (full brightness)
00294 #ifndef MICROBIT_DISPLAY_DEFAULT_BRIGHTNESS
00295 #define MICROBIT_DISPLAY_DEFAULT_BRIGHTNESS     MICROBIT_DISPLAY_MAXIMUM_BRIGHTNESS
00296 #endif
00297 
00298 // Selects the default scroll speed for the display.
00299 // The time taken to move a single pixel (ms).
00300 #ifndef MICROBIT_DEFAULT_SCROLL_SPEED
00301 #define MICROBIT_DEFAULT_SCROLL_SPEED           120
00302 #endif
00303 
00304 // Selects the number of pixels a scroll will move in each quantum.
00305 #ifndef MICROBIT_DEFAULT_SCROLL_STRIDE
00306 #define MICROBIT_DEFAULT_SCROLL_STRIDE          -1
00307 #endif
00308 
00309 // Selects the time each character will be shown on the display during print operations.
00310 // The time each character is shown on the screen  (ms).
00311 #ifndef MICROBIT_DEFAULT_PRINT_SPEED
00312 #define MICROBIT_DEFAULT_PRINT_SPEED            400
00313 #endif
00314 
00315 //Configures the default serial mode used by serial read and send calls.
00316 #ifndef MICROBIT_DEFAULT_SERIAL_MODE
00317 #define MICROBIT_DEFAULT_SERIAL_MODE            SYNC_SLEEP
00318 #endif
00319 
00320 
00321 //
00322 // Panic options
00323 //
00324 
00325 // Enable this to invoke a panic on out of memory conditions.
00326 // Set '1' to enable.
00327 #ifndef MICROBIT_PANIC_HEAP_FULL
00328 #define MICROBIT_PANIC_HEAP_FULL                1
00329 #endif
00330 
00331 //
00332 // Debug options
00333 //
00334 
00335 // Enable this to route debug messages through the USB serial interface.
00336 // n.b. This also disables the user serial port 'uBit.serial'.
00337 // Set '1' to enable.
00338 #ifndef MICROBIT_DBG
00339 #define MICROBIT_DBG                            0
00340 #endif
00341 
00342 // Enable this to receive diagnostic messages from the heap allocator via the USB serial interface.
00343 // n.b. This requires MICROBIT_DBG to be defined.
00344 // Set '1' to enable.
00345 #ifndef MICROBIT_HEAP_DBG
00346 #define MICROBIT_HEAP_DBG                       0
00347 #endif
00348 
00349 // Versioning options.
00350 // We use semantic versioning (http://semver.org/) to identify differnet versions of the micro:bit runtime.
00351 // Where possible we use yotta (an ARM mbed build tool) to help us track versions.
00352 // if this isn't available, it can be defined manually as a configuration option.
00353 //
00354 #ifndef MICROBIT_DAL_VERSION
00355 #define MICROBIT_DAL_VERSION                    "0.1.0-node"
00356 #endif
00357 
00358 
00359 //
00360 // Helper macro used by the micro:bit runtime to determine if a boolean configuration option is set.
00361 //
00362 #define CONFIG_ENABLED(X) (X == 1)
00363 #define CONFIG_DISABLED(X) (X != 1)
00364 
00365 #if CONFIG_ENABLED(MICROBIT_HEAP_ALLOCATOR)
00366 #include "MicroBitHeapAllocator.h"
00367 #endif
00368 
00369 #if CONFIG_ENABLED(MICROBIT_DBG)
00370 extern RawSerial* SERIAL_DEBUG;
00371 #endif
00372 
00373 #endif