Unverified Commit b41667b8 authored by Marcel Stör's avatar Marcel Stör Committed by GitHub
Browse files

Master drop #2486

Dev -> Master Release 10
parents f99f295d 0abb2617
/*
u8g_rect.c
U8G high level interface for horizontal and vertical things
Universal 8bit Graphics Library
Copyright (c) 2011, olikraus@gmail.com
All rights reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list
of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or other
materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#include "u8g.h"
void u8g_draw_hline(u8g_t *u8g, u8g_uint_t x, u8g_uint_t y, u8g_uint_t w)
{
uint8_t pixel = 0x0ff;
while( w >= 8 )
{
u8g_Draw8Pixel(u8g, x, y, 0, pixel);
w-=8;
x+=8;
}
if ( w != 0 )
{
w ^=7;
w++;
pixel <<= w&7;
u8g_Draw8Pixel(u8g, x, y, 0, pixel);
}
}
void u8g_draw_vline(u8g_t *u8g, u8g_uint_t x, u8g_uint_t y, u8g_uint_t h)
{
uint8_t pixel = 0x0ff;
while( h >= 8 )
{
u8g_Draw8Pixel(u8g, x, y, 1, pixel);
h-=8;
y+=8;
}
if ( h != 0 )
{
h ^=7;
h++;
pixel <<= h&7;
u8g_Draw8Pixel(u8g, x, y, 1, pixel);
}
}
void u8g_DrawHLine(u8g_t *u8g, u8g_uint_t x, u8g_uint_t y, u8g_uint_t w)
{
if ( u8g_IsBBXIntersection(u8g, x, y, w, 1) == 0 )
return;
u8g_draw_hline(u8g, x, y, w);
}
void u8g_DrawVLine(u8g_t *u8g, u8g_uint_t x, u8g_uint_t y, u8g_uint_t w)
{
if ( u8g_IsBBXIntersection(u8g, x, y, 1, w) == 0 )
return;
u8g_draw_vline(u8g, x, y, w);
}
/* restrictions: w > 0 && h > 0 */
void u8g_DrawFrame(u8g_t *u8g, u8g_uint_t x, u8g_uint_t y, u8g_uint_t w, u8g_uint_t h)
{
u8g_uint_t xtmp = x;
if ( u8g_IsBBXIntersection(u8g, x, y, w, h) == 0 )
return;
u8g_draw_hline(u8g, x, y, w);
u8g_draw_vline(u8g, x, y, h);
x+=w;
x--;
u8g_draw_vline(u8g, x, y, h);
y+=h;
y--;
u8g_draw_hline(u8g, xtmp, y, w);
}
void u8g_draw_box(u8g_t *u8g, u8g_uint_t x, u8g_uint_t y, u8g_uint_t w, u8g_uint_t h)
{
do
{
u8g_draw_hline(u8g, x, y, w);
y++;
h--;
} while( h != 0 );
}
/* restrictions: h > 0 */
void u8g_DrawBox(u8g_t *u8g, u8g_uint_t x, u8g_uint_t y, u8g_uint_t w, u8g_uint_t h)
{
if ( u8g_IsBBXIntersection(u8g, x, y, w, h) == 0 )
return;
u8g_draw_box(u8g, x, y, w, h);
}
void u8g_DrawRFrame(u8g_t *u8g, u8g_uint_t x, u8g_uint_t y, u8g_uint_t w, u8g_uint_t h, u8g_uint_t r)
{
u8g_uint_t xl, yu;
if ( u8g_IsBBXIntersection(u8g, x, y, w, h) == 0 )
return;
xl = x;
xl += r;
yu = y;
yu += r;
{
u8g_uint_t yl, xr;
xr = x;
xr += w;
xr -= r;
xr -= 1;
yl = y;
yl += h;
yl -= r;
yl -= 1;
u8g_draw_circle(u8g, xl, yu, r, U8G_DRAW_UPPER_LEFT);
u8g_draw_circle(u8g, xr, yu, r, U8G_DRAW_UPPER_RIGHT);
u8g_draw_circle(u8g, xl, yl, r, U8G_DRAW_LOWER_LEFT);
u8g_draw_circle(u8g, xr, yl, r, U8G_DRAW_LOWER_RIGHT);
}
{
u8g_uint_t ww, hh;
ww = w;
ww -= r;
ww -= r;
ww -= 2;
hh = h;
hh -= r;
hh -= r;
hh -= 2;
xl++;
yu++;
h--;
w--;
u8g_draw_hline(u8g, xl, y, ww);
u8g_draw_hline(u8g, xl, y+h, ww);
u8g_draw_vline(u8g, x, yu, hh);
u8g_draw_vline(u8g, x+w, yu, hh);
}
}
void u8g_DrawRBox(u8g_t *u8g, u8g_uint_t x, u8g_uint_t y, u8g_uint_t w, u8g_uint_t h, u8g_uint_t r)
{
u8g_uint_t xl, yu;
u8g_uint_t yl, xr;
if ( u8g_IsBBXIntersection(u8g, x, y, w, h) == 0 )
return;
xl = x;
xl += r;
yu = y;
yu += r;
xr = x;
xr += w;
xr -= r;
xr -= 1;
yl = y;
yl += h;
yl -= r;
yl -= 1;
u8g_draw_disc(u8g, xl, yu, r, U8G_DRAW_UPPER_LEFT);
u8g_draw_disc(u8g, xr, yu, r, U8G_DRAW_UPPER_RIGHT);
u8g_draw_disc(u8g, xl, yl, r, U8G_DRAW_LOWER_LEFT);
u8g_draw_disc(u8g, xr, yl, r, U8G_DRAW_LOWER_RIGHT);
{
u8g_uint_t ww, hh;
ww = w;
ww -= r;
ww -= r;
ww -= 2;
hh = h;
hh -= r;
hh -= r;
hh -= 2;
xl++;
yu++;
h--;
u8g_draw_box(u8g, xl, y, ww, r+1);
u8g_draw_box(u8g, xl, yl, ww, r+1);
//u8g_draw_hline(u8g, xl, y+h, ww);
u8g_draw_box(u8g, x, yu, w, hh);
//u8g_draw_vline(u8g, x+w, yu, hh);
}
}
/*
u8g_rot.c
Universal 8bit Graphics Library
Copyright (c) 2011, olikraus@gmail.com
All rights reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list
of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or other
materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#include "u8g.h"
uint8_t u8g_dev_rot90_fn(u8g_t *u8g, u8g_dev_t *dev, uint8_t msg, void *arg);
uint8_t u8g_dev_rot180_fn(u8g_t *u8g, u8g_dev_t *dev, uint8_t msg, void *arg);
uint8_t u8g_dev_rot270_fn(u8g_t *u8g, u8g_dev_t *dev, uint8_t msg, void *arg);
uint8_t u8g_dev_rot_dummy_fn(u8g_t *u8g, u8g_dev_t*dev, uint8_t msg, void *arg)
{
return 0;
}
u8g_dev_t u8g_dev_rot = { u8g_dev_rot_dummy_fn, NULL, NULL };
void u8g_UndoRotation(u8g_t *u8g)
{
if ( u8g->dev != &u8g_dev_rot )
return;
u8g->dev = u8g_dev_rot.dev_mem;
u8g_UpdateDimension(u8g);
}
void u8g_SetRot90(u8g_t *u8g)
{
if ( u8g->dev != &u8g_dev_rot )
{
u8g_dev_rot.dev_mem = u8g->dev;
u8g->dev = &u8g_dev_rot;
}
u8g_dev_rot.dev_fn = u8g_dev_rot90_fn;
u8g_UpdateDimension(u8g);
}
void u8g_SetRot180(u8g_t *u8g)
{
if ( u8g->dev != &u8g_dev_rot )
{
u8g_dev_rot.dev_mem = u8g->dev;
u8g->dev = &u8g_dev_rot;
}
u8g_dev_rot.dev_fn = u8g_dev_rot180_fn;
u8g_UpdateDimension(u8g);
}
void u8g_SetRot270(u8g_t *u8g)
{
if ( u8g->dev != &u8g_dev_rot )
{
u8g_dev_rot.dev_mem = u8g->dev;
u8g->dev = &u8g_dev_rot;
}
u8g_dev_rot.dev_fn = u8g_dev_rot270_fn;
u8g_UpdateDimension(u8g);
}
uint8_t u8g_dev_rot90_fn(u8g_t *u8g, u8g_dev_t *dev, uint8_t msg, void *arg)
{
u8g_dev_t *rotation_chain = (u8g_dev_t *)(dev->dev_mem);
switch(msg)
{
default:
/*
case U8G_DEV_MSG_INIT:
case U8G_DEV_MSG_STOP:
case U8G_DEV_MSG_PAGE_FIRST:
case U8G_DEV_MSG_PAGE_NEXT:
case U8G_DEV_MSG_SET_COLOR_ENTRY:
case U8G_DEV_MSG_SET_XY_CB:
*/
return u8g_call_dev_fn(u8g, rotation_chain, msg, arg);
#ifdef U8G_DEV_MSG_IS_BBX_INTERSECTION
case U8G_DEV_MSG_IS_BBX_INTERSECTION:
{
u8g_dev_arg_bbx_t *bbx = (u8g_dev_arg_bbx_t *)arg;
u8g_uint_t x, y, tmp;
/* transform the reference point */
y = bbx->x;
x = u8g->height;
/* x = u8g_GetWidthLL(u8g, rotation_chain); */
x -= bbx->y;
x--;
/* adjust point to be the uppler left corner again */
x -= bbx->h;
x++;
/* swap box dimensions */
tmp = bbx->w;
bbx->w = bbx->h;
bbx->h = tmp;
/* store x,y */
bbx->x = x;
bbx->y = y;
}
return u8g_call_dev_fn(u8g, rotation_chain, msg, arg);
#endif /* U8G_DEV_MSG_IS_BBX_INTERSECTION */
case U8G_DEV_MSG_GET_PAGE_BOX:
/* get page size from next device in the chain */
u8g_call_dev_fn(u8g, rotation_chain, msg, arg);
//printf("pre x: %3d..%3d y: %3d..%3d ", ((u8g_box_t *)arg)->x0, ((u8g_box_t *)arg)->x1, ((u8g_box_t *)arg)->y0, ((u8g_box_t *)arg)->y1);
{
u8g_box_t new_box;
//new_box.x0 = u8g_GetHeightLL(u8g,rotation_chain) - ((u8g_box_t *)arg)->y1 - 1;
//new_box.x1 = u8g_GetHeightLL(u8g,rotation_chain) - ((u8g_box_t *)arg)->y0 - 1;
new_box.x0 = ((u8g_box_t *)arg)->y0;
new_box.x1 = ((u8g_box_t *)arg)->y1;
new_box.y0 = ((u8g_box_t *)arg)->x0;
new_box.y1 = ((u8g_box_t *)arg)->x1;
*((u8g_box_t *)arg) = new_box;
//printf("post x: %3d..%3d y: %3d..%3d\n", ((u8g_box_t *)arg)->x0, ((u8g_box_t *)arg)->x1, ((u8g_box_t *)arg)->y0, ((u8g_box_t *)arg)->y1);
}
break;
case U8G_DEV_MSG_GET_WIDTH:
*((u8g_uint_t *)arg) = u8g_GetHeightLL(u8g,rotation_chain);
break;
case U8G_DEV_MSG_GET_HEIGHT:
*((u8g_uint_t *)arg) = u8g_GetWidthLL(u8g, rotation_chain);
break;
case U8G_DEV_MSG_SET_PIXEL:
case U8G_DEV_MSG_SET_TPIXEL:
{
u8g_uint_t x, y;
y = ((u8g_dev_arg_pixel_t *)arg)->x;
x = u8g_GetWidthLL(u8g, rotation_chain);
x -= ((u8g_dev_arg_pixel_t *)arg)->y;
x--;
((u8g_dev_arg_pixel_t *)arg)->x = x;
((u8g_dev_arg_pixel_t *)arg)->y = y;
}
u8g_call_dev_fn(u8g, rotation_chain, msg, arg);
break;
case U8G_DEV_MSG_SET_8PIXEL:
case U8G_DEV_MSG_SET_4TPIXEL:
{
u8g_uint_t x, y;
//uint16_t x,y;
y = ((u8g_dev_arg_pixel_t *)arg)->x;
x = u8g_GetWidthLL(u8g, rotation_chain);
x -= ((u8g_dev_arg_pixel_t *)arg)->y;
x--;
((u8g_dev_arg_pixel_t *)arg)->x = x;
((u8g_dev_arg_pixel_t *)arg)->y = y;
((u8g_dev_arg_pixel_t *)arg)->dir+=1;
((u8g_dev_arg_pixel_t *)arg)->dir &= 3;
}
u8g_call_dev_fn(u8g, rotation_chain, msg, arg);
break;
}
return 1;
}
uint8_t u8g_dev_rot180_fn(u8g_t *u8g, u8g_dev_t *dev, uint8_t msg, void *arg)
{
u8g_dev_t *rotation_chain = (u8g_dev_t *)(dev->dev_mem);
switch(msg)
{
default:
/*
case U8G_DEV_MSG_INIT:
case U8G_DEV_MSG_STOP:
case U8G_DEV_MSG_PAGE_FIRST:
case U8G_DEV_MSG_PAGE_NEXT:
case U8G_DEV_MSG_SET_COLOR_ENTRY:
case U8G_DEV_MSG_SET_XY_CB:
*/
return u8g_call_dev_fn(u8g, rotation_chain, msg, arg);
#ifdef U8G_DEV_MSG_IS_BBX_INTERSECTION
case U8G_DEV_MSG_IS_BBX_INTERSECTION:
{
u8g_dev_arg_bbx_t *bbx = (u8g_dev_arg_bbx_t *)arg;
u8g_uint_t x, y;
/* transform the reference point */
//y = u8g_GetHeightLL(u8g, rotation_chain);
y = u8g->height;
y -= bbx->y;
y--;
//x = u8g_GetWidthLL(u8g, rotation_chain);
x = u8g->width;
x -= bbx->x;
x--;
/* adjust point to be the uppler left corner again */
y -= bbx->h;
y++;
x -= bbx->w;
x++;
/* store x,y */
bbx->x = x;
bbx->y = y;
}
return u8g_call_dev_fn(u8g, rotation_chain, msg, arg);
#endif /* U8G_DEV_MSG_IS_BBX_INTERSECTION */
case U8G_DEV_MSG_GET_PAGE_BOX:
/* get page size from next device in the chain */
u8g_call_dev_fn(u8g, rotation_chain, msg, arg);
//printf("pre x: %3d..%3d y: %3d..%3d ", ((u8g_box_t *)arg)->x0, ((u8g_box_t *)arg)->x1, ((u8g_box_t *)arg)->y0, ((u8g_box_t *)arg)->y1);
{
u8g_box_t new_box;
new_box.x0 = u8g_GetWidthLL(u8g,rotation_chain) - ((u8g_box_t *)arg)->x1 - 1;
new_box.x1 = u8g_GetWidthLL(u8g,rotation_chain) - ((u8g_box_t *)arg)->x0 - 1;
new_box.y0 = u8g_GetHeightLL(u8g,rotation_chain) - ((u8g_box_t *)arg)->y1 - 1;
new_box.y1 = u8g_GetHeightLL(u8g,rotation_chain) - ((u8g_box_t *)arg)->y0 - 1;
*((u8g_box_t *)arg) = new_box;
//printf("post x: %3d..%3d y: %3d..%3d\n", ((u8g_box_t *)arg)->x0, ((u8g_box_t *)arg)->x1, ((u8g_box_t *)arg)->y0, ((u8g_box_t *)arg)->y1);
}
break;
case U8G_DEV_MSG_GET_WIDTH:
*((u8g_uint_t *)arg) = u8g_GetWidthLL(u8g,rotation_chain);
break;
case U8G_DEV_MSG_GET_HEIGHT:
*((u8g_uint_t *)arg) = u8g_GetHeightLL(u8g, rotation_chain);
break;
case U8G_DEV_MSG_SET_PIXEL:
case U8G_DEV_MSG_SET_TPIXEL:
{
u8g_uint_t x, y;
y = u8g_GetHeightLL(u8g, rotation_chain);
y -= ((u8g_dev_arg_pixel_t *)arg)->y;
y--;
x = u8g_GetWidthLL(u8g, rotation_chain);
x -= ((u8g_dev_arg_pixel_t *)arg)->x;
x--;
((u8g_dev_arg_pixel_t *)arg)->x = x;
((u8g_dev_arg_pixel_t *)arg)->y = y;
}
u8g_call_dev_fn(u8g, rotation_chain, msg, arg);
break;
case U8G_DEV_MSG_SET_8PIXEL:
case U8G_DEV_MSG_SET_4TPIXEL:
{
u8g_uint_t x, y;
y = u8g_GetHeightLL(u8g, rotation_chain);
y -= ((u8g_dev_arg_pixel_t *)arg)->y;
y--;
x = u8g_GetWidthLL(u8g, rotation_chain);
x -= ((u8g_dev_arg_pixel_t *)arg)->x;
x--;
((u8g_dev_arg_pixel_t *)arg)->x = x;
((u8g_dev_arg_pixel_t *)arg)->y = y;
((u8g_dev_arg_pixel_t *)arg)->dir+=2;
((u8g_dev_arg_pixel_t *)arg)->dir &= 3;
}
u8g_call_dev_fn(u8g, rotation_chain, msg, arg);
break;
}
return 1;
}
uint8_t u8g_dev_rot270_fn(u8g_t *u8g, u8g_dev_t *dev, uint8_t msg, void *arg)
{
u8g_dev_t *rotation_chain = (u8g_dev_t *)(dev->dev_mem);
switch(msg)
{
default:
/*
case U8G_DEV_MSG_INIT:
case U8G_DEV_MSG_STOP:
case U8G_DEV_MSG_PAGE_FIRST:
case U8G_DEV_MSG_PAGE_NEXT:
case U8G_DEV_MSG_SET_COLOR_ENTRY:
case U8G_DEV_MSG_SET_XY_CB:
*/
return u8g_call_dev_fn(u8g, rotation_chain, msg, arg);
#ifdef U8G_DEV_MSG_IS_BBX_INTERSECTION
case U8G_DEV_MSG_IS_BBX_INTERSECTION:
{
u8g_dev_arg_bbx_t *bbx = (u8g_dev_arg_bbx_t *)arg;
u8g_uint_t x, y, tmp;
/* transform the reference point */
x = bbx->y;
y = u8g->width;
/* y = u8g_GetHeightLL(u8g, rotation_chain); */
y -= bbx->x;
y--;
/* adjust point to be the uppler left corner again */
y -= bbx->w;
y++;
/* swap box dimensions */
tmp = bbx->w;
bbx->w = bbx->h;
bbx->h = tmp;
/* store x,y */
bbx->x = x;
bbx->y = y;
}
return u8g_call_dev_fn(u8g, rotation_chain, msg, arg);
#endif /* U8G_DEV_MSG_IS_BBX_INTERSECTION */
case U8G_DEV_MSG_GET_PAGE_BOX:
/* get page size from next device in the chain */
u8g_call_dev_fn(u8g, rotation_chain, msg, arg);
//printf("pre x: %3d..%3d y: %3d..%3d ", ((u8g_box_t *)arg)->x0, ((u8g_box_t *)arg)->x1, ((u8g_box_t *)arg)->y0, ((u8g_box_t *)arg)->y1);
{
u8g_box_t new_box;
new_box.x0 = u8g_GetHeightLL(u8g,rotation_chain) - ((u8g_box_t *)arg)->y1 - 1;
new_box.x1 = u8g_GetHeightLL(u8g,rotation_chain) - ((u8g_box_t *)arg)->y0 - 1;
new_box.y0 = u8g_GetWidthLL(u8g,rotation_chain) - ((u8g_box_t *)arg)->x1 - 1;
new_box.y1 = u8g_GetWidthLL(u8g,rotation_chain) - ((u8g_box_t *)arg)->x0 - 1;
*((u8g_box_t *)arg) = new_box;
//printf("post x: %3d..%3d y: %3d..%3d\n", ((u8g_box_t *)arg)->x0, ((u8g_box_t *)arg)->x1, ((u8g_box_t *)arg)->y0, ((u8g_box_t *)arg)->y1);
}
break;
case U8G_DEV_MSG_GET_WIDTH:
*((u8g_uint_t *)arg) = u8g_GetHeightLL(u8g,rotation_chain);
break;
case U8G_DEV_MSG_GET_HEIGHT:
*((u8g_uint_t *)arg) = u8g_GetWidthLL(u8g, rotation_chain);
break;
case U8G_DEV_MSG_SET_PIXEL:
case U8G_DEV_MSG_SET_TPIXEL:
{
u8g_uint_t x, y;
x = ((u8g_dev_arg_pixel_t *)arg)->y;
y = u8g_GetHeightLL(u8g, rotation_chain);
y -= ((u8g_dev_arg_pixel_t *)arg)->x;
y--;
/*
x = u8g_GetWidthLL(u8g, rotation_chain);
x -= ((u8g_dev_arg_pixel_t *)arg)->y;
x--;
*/
((u8g_dev_arg_pixel_t *)arg)->x = x;
((u8g_dev_arg_pixel_t *)arg)->y = y;
}
u8g_call_dev_fn(u8g, rotation_chain, msg, arg);
break;
case U8G_DEV_MSG_SET_8PIXEL:
case U8G_DEV_MSG_SET_4TPIXEL:
{
u8g_uint_t x, y;
x = ((u8g_dev_arg_pixel_t *)arg)->y;
y = u8g_GetHeightLL(u8g, rotation_chain);
y -= ((u8g_dev_arg_pixel_t *)arg)->x;
y--;
/*
x = u8g_GetWidthLL(u8g, rotation_chain);
x -= ((u8g_dev_arg_pixel_t *)arg)->y;
x--;
*/
((u8g_dev_arg_pixel_t *)arg)->x = x;
((u8g_dev_arg_pixel_t *)arg)->y = y;
((u8g_dev_arg_pixel_t *)arg)->dir+=3;
((u8g_dev_arg_pixel_t *)arg)->dir &= 3;
}
u8g_call_dev_fn(u8g, rotation_chain, msg, arg);
break;
}
return 1;
}
/*
u8g_scale.c
Universal 8bit Graphics Library
Copyright (c) 2012, olikraus@gmail.com
All rights reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list
of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or other
materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Scale screen by some constant factors. Usefull for making bigger fonts wiht less
memory consumption
*/
#include "u8g.h"
uint8_t u8g_dev_scale_2x2_fn(u8g_t *u8g, u8g_dev_t *dev, uint8_t msg, void *arg);
u8g_dev_t u8g_dev_scale = { u8g_dev_scale_2x2_fn, NULL, NULL };
void u8g_UndoScale(u8g_t *u8g)
{
if ( u8g->dev != &u8g_dev_scale )
return;
u8g->dev = u8g_dev_scale.dev_mem;
u8g_UpdateDimension(u8g);
}
void u8g_SetScale2x2(u8g_t *u8g)
{
if ( u8g->dev != &u8g_dev_scale )
{
u8g_dev_scale.dev_mem = u8g->dev;
u8g->dev = &u8g_dev_scale;
}
u8g_dev_scale.dev_fn = u8g_dev_scale_2x2_fn;
u8g_UpdateDimension(u8g);
}
uint8_t u8g_dev_scale_2x2_fn(u8g_t *u8g, u8g_dev_t *dev, uint8_t msg, void *arg)
{
u8g_dev_t *chain = (u8g_dev_t *)(dev->dev_mem);
uint8_t pixel;
uint16_t scaled_pixel;
uint8_t i;
uint8_t dir;
u8g_uint_t x, y, xx,yy;
switch(msg)
{
default:
return u8g_call_dev_fn(u8g, chain, msg, arg);
case U8G_DEV_MSG_GET_WIDTH:
*((u8g_uint_t *)arg) = u8g_GetWidthLL(u8g, chain) / 2;
break;
case U8G_DEV_MSG_GET_HEIGHT:
*((u8g_uint_t *)arg) = u8g_GetHeightLL(u8g, chain) / 2;
break;
case U8G_DEV_MSG_GET_PAGE_BOX:
/* get page size from next device in the chain */
u8g_call_dev_fn(u8g, chain, msg, arg);
((u8g_box_t *)arg)->x0 /= 2;
((u8g_box_t *)arg)->x1 /= 2;
((u8g_box_t *)arg)->y0 /= 2;
((u8g_box_t *)arg)->y1 /= 2;
return 1;
case U8G_DEV_MSG_SET_PIXEL:
x = ((u8g_dev_arg_pixel_t *)arg)->x;
x *= 2;
y = ((u8g_dev_arg_pixel_t *)arg)->y;
y *= 2;
((u8g_dev_arg_pixel_t *)arg)->x = x;
((u8g_dev_arg_pixel_t *)arg)->y = y;
u8g_call_dev_fn(u8g, chain, msg, arg);
x++;
((u8g_dev_arg_pixel_t *)arg)->x = x;
((u8g_dev_arg_pixel_t *)arg)->y = y;
u8g_call_dev_fn(u8g, chain, msg, arg);
y++;
((u8g_dev_arg_pixel_t *)arg)->x = x;
((u8g_dev_arg_pixel_t *)arg)->y = y;
u8g_call_dev_fn(u8g, chain, msg, arg);
x--;
((u8g_dev_arg_pixel_t *)arg)->x = x;
((u8g_dev_arg_pixel_t *)arg)->y = y;
u8g_call_dev_fn(u8g, chain, msg, arg);
break;
case U8G_DEV_MSG_SET_8PIXEL:
pixel = ((u8g_dev_arg_pixel_t *)arg)->pixel;
dir = ((u8g_dev_arg_pixel_t *)arg)->dir;
scaled_pixel = 0;
for( i = 0; i < 8; i++ )
{
scaled_pixel<<=2;
if ( pixel & 128 )
{
scaled_pixel |= 3;
}
pixel<<=1;
}
x = ((u8g_dev_arg_pixel_t *)arg)->x;
x *= 2;
xx = x;
y = ((u8g_dev_arg_pixel_t *)arg)->y;
y *= 2;
yy = y;
if ( ((u8g_dev_arg_pixel_t *)arg)->dir & 1 )
{
xx++;
}
else
{
yy++;
}
((u8g_dev_arg_pixel_t *)arg)->pixel = scaled_pixel>>8;
((u8g_dev_arg_pixel_t *)arg)->x = x;
((u8g_dev_arg_pixel_t *)arg)->y = y;
((u8g_dev_arg_pixel_t *)arg)->dir = dir;
u8g_call_dev_fn(u8g, chain, msg, arg);
((u8g_dev_arg_pixel_t *)arg)->x = xx;
((u8g_dev_arg_pixel_t *)arg)->y = yy;
((u8g_dev_arg_pixel_t *)arg)->dir = dir;
u8g_call_dev_fn(u8g, chain, msg, arg);
((u8g_dev_arg_pixel_t *)arg)->pixel = scaled_pixel&255;
//((u8g_dev_arg_pixel_t *)arg)->pixel = 0x00;
switch(dir)
{
case 0:
x+=8;
xx+=8;
break;
case 1:
y+=8;
yy+=8;
break;
case 2:
x-=8;
xx-=8;
break;
case 3:
y-=8;
yy-=8;
break;
}
((u8g_dev_arg_pixel_t *)arg)->x = x;
((u8g_dev_arg_pixel_t *)arg)->y = y;
((u8g_dev_arg_pixel_t *)arg)->dir = dir;
u8g_call_dev_fn(u8g, chain, msg, arg);
((u8g_dev_arg_pixel_t *)arg)->x = xx;
((u8g_dev_arg_pixel_t *)arg)->y = yy;
((u8g_dev_arg_pixel_t *)arg)->dir = dir;
u8g_call_dev_fn(u8g, chain, msg, arg);
break;
}
return 1;
}
/*
u8g_state.c
backup and restore hardware state
Universal 8bit Graphics Library
Copyright (c) 2011, olikraus@gmail.com
All rights reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list
of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or other
materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
state callback: backup env U8G_STATE_MSG_BACKUP_ENV
device callback: DEV_MSG_INIT
state callback: backup u8g U8G_STATE_MSG_BACKUP_U8G
state callback: restore env U8G_STATE_MSG_RESTORE_ENV
state callback: backup env U8G_STATE_MSG_BACKUP_ENV
state callback: retore u8g U8G_STATE_MSG_RESTORE_U8G
DEV_MSG_PAGE_FIRST or DEV_MSG_PAGE_NEXT
state callback: restore env U8G_STATE_MSG_RESTORE_ENV
*/
#include <stddef.h>
#include "u8g.h"
void u8g_state_dummy_cb(uint8_t msg)
{
/* the dummy procedure does nothing */
}
void u8g_SetHardwareBackup(u8g_t *u8g, u8g_state_cb backup_cb)
{
u8g->state_cb = backup_cb;
/* in most cases the init message was already sent, so this will backup the */
/* current u8g state */
backup_cb(U8G_STATE_MSG_BACKUP_U8G);
}
/*===============================================================*/
/* register variable for restoring interrupt state */
#if defined(__AVR__)
uint8_t global_SREG_backup;
#endif
/*===============================================================*/
/* AVR */
#if defined(__AVR_XMEGA__)
#elif defined(__AVR__)
#define U8G_ATMEGA_HW_SPI
/* remove the definition for attiny */
#if __AVR_ARCH__ == 2
#undef U8G_ATMEGA_HW_SPI
#endif
#if __AVR_ARCH__ == 25
#undef U8G_ATMEGA_HW_SPI
#endif
#endif
#if defined(U8G_ATMEGA_HW_SPI)
#include <avr/interrupt.h>
static uint8_t u8g_state_avr_spi_memory[2];
void u8g_backup_spi(uint8_t msg)
{
if ( U8G_STATE_MSG_IS_BACKUP(msg) )
{
u8g_state_avr_spi_memory[U8G_STATE_MSG_GET_IDX(msg)] = SPCR;
}
else
{
uint8_t tmp = SREG;
cli();
SPCR = 0;
SPCR = u8g_state_avr_spi_memory[U8G_STATE_MSG_GET_IDX(msg)];
SREG = tmp;
}
}
#elif defined (U8G_RASPBERRY_PI)
#include <stdio.h>
void u8g_backup_spi(uint8_t msg) {
printf("u8g_backup_spi %d\r\n",msg);
}
#elif defined(ARDUINO) && defined(__SAM3X8E__) // Arduino Due, maybe we should better check for __SAM3X8E__
#include "sam.h"
struct sam_backup_struct
{
uint32_t mr;
uint32_t sr;
uint32_t csr[4];
} sam_backup[2];
void u8g_backup_spi(uint8_t msg)
{
uint8_t idx = U8G_STATE_MSG_GET_IDX(msg);
if ( U8G_STATE_MSG_IS_BACKUP(msg) )
{
sam_backup[idx].mr = SPI0->SPI_MR;
sam_backup[idx].sr = SPI0->SPI_SR;
sam_backup[idx].csr[0] = SPI0->SPI_CSR[0];
sam_backup[idx].csr[1] = SPI0->SPI_CSR[1];
sam_backup[idx].csr[2] = SPI0->SPI_CSR[2];
sam_backup[idx].csr[3] = SPI0->SPI_CSR[3];
}
else
{
SPI0->SPI_MR = sam_backup[idx].mr;
SPI0->SPI_CSR[0] = sam_backup[idx].csr[0];
SPI0->SPI_CSR[1] = sam_backup[idx].csr[1];
SPI0->SPI_CSR[2] = sam_backup[idx].csr[2];
SPI0->SPI_CSR[3] = sam_backup[idx].csr[3];
}
}
#else
void u8g_backup_spi(uint8_t msg)
{
}
#endif
/*
u8g_u16toa.c
Universal 8bit Graphics Library
Copyright (c) 2012, olikraus@gmail.com
All rights reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list
of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or other
materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#include "u8g.h"
const char *u8g_u16toap(char * dest, uint16_t v)
{
uint8_t pos;
uint8_t d;
uint16_t c;
c = 10000;
for( pos = 0; pos < 5; pos++ )
{
d = '0';
while( v >= c )
{
v -= c;
d++;
}
dest[pos] = d;
c /= 10;
}
dest[5] = '\0';
return dest;
}
/* v = value, d = number of digits */
const char *u8g_u16toa(uint16_t v, uint8_t d)
{
static char buf[6];
d = 5-d;
return u8g_u16toap(buf, v) + d;
}
/*
u8g_u8toa.c
Universal 8bit Graphics Library
Copyright (c) 2011, olikraus@gmail.com
All rights reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list
of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or other
materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#include "u8g.h"
static const unsigned char u8g_u8toa_tab[3] = { 100, 10, 1 } ;
const char *u8g_u8toap(char * dest, uint8_t v)
{
uint8_t pos;
uint8_t d;
uint8_t c;
for( pos = 0; pos < 3; pos++ )
{
d = '0';
c = *(u8g_u8toa_tab+pos);
while( v >= c )
{
v -= c;
d++;
}
dest[pos] = d;
}
dest[3] = '\0';
return dest;
}
/* v = value, d = number of digits */
const char *u8g_u8toa(uint8_t v, uint8_t d)
{
static char buf[4];
d = 3-d;
return u8g_u8toap(buf, v) + d;
}
/*
u8g_virtual_screen.c
Universal 8bit Graphics Library
Copyright (c) 2012, olikraus@gmail.com
All rights reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list
of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or other
materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#include "u8g.h"
struct _u8g_vs_t
{
u8g_uint_t x;
u8g_uint_t y;
u8g_t *u8g;
};
typedef struct _u8g_vs_t u8g_vs_t;
#define U8g_VS_MAX 4
uint8_t u8g_vs_cnt = 0;
u8g_vs_t u8g_vs_list[U8g_VS_MAX];
uint8_t u8g_vs_current;
u8g_uint_t u8g_vs_width;
u8g_uint_t u8g_vs_height;
uint8_t u8g_dev_vs_fn(u8g_t *u8g, u8g_dev_t *dev, uint8_t msg, void *arg)
{
switch(msg)
{
default:
{
uint8_t i;
for( i = 0; i < u8g_vs_cnt; i++ )
{
u8g_call_dev_fn(u8g_vs_list[i].u8g, u8g_vs_list[i].u8g->dev, msg, arg);
}
}
return 1;
case U8G_DEV_MSG_PAGE_FIRST:
u8g_vs_current = 0;
if ( u8g_vs_cnt != 0 )
return u8g_call_dev_fn(u8g_vs_list[u8g_vs_current].u8g, u8g_vs_list[u8g_vs_current].u8g->dev, msg, arg);
return 0;
case U8G_DEV_MSG_PAGE_NEXT:
{
uint8_t ret = 0;
if ( u8g_vs_cnt != 0 )
ret = u8g_call_dev_fn(u8g_vs_list[u8g_vs_current].u8g, u8g_vs_list[u8g_vs_current].u8g->dev, msg, arg);
if ( ret != 0 )
return ret;
u8g_vs_current++; /* next device */
if ( u8g_vs_current >= u8g_vs_cnt ) /* reached end? */
return 0;
return u8g_call_dev_fn(u8g_vs_list[u8g_vs_current].u8g, u8g_vs_list[u8g_vs_current].u8g->dev, U8G_DEV_MSG_PAGE_FIRST, arg);
}
case U8G_DEV_MSG_GET_WIDTH:
*((u8g_uint_t *)arg) = u8g_vs_width;
break;
case U8G_DEV_MSG_GET_HEIGHT:
*((u8g_uint_t *)arg) = u8g_vs_height;
break;
case U8G_DEV_MSG_GET_PAGE_BOX:
if ( u8g_vs_current < u8g_vs_cnt )
{
u8g_call_dev_fn(u8g_vs_list[u8g_vs_current].u8g, u8g_vs_list[u8g_vs_current].u8g->dev, msg, arg);
((u8g_box_t *)arg)->x0 += u8g_vs_list[u8g_vs_current].x;
((u8g_box_t *)arg)->x1 += u8g_vs_list[u8g_vs_current].x;
((u8g_box_t *)arg)->y0 += u8g_vs_list[u8g_vs_current].y;
((u8g_box_t *)arg)->y1 += u8g_vs_list[u8g_vs_current].y;
}
else
{
((u8g_box_t *)arg)->x0 = 0;
((u8g_box_t *)arg)->x1 = 0;
((u8g_box_t *)arg)->y0 = 0;
((u8g_box_t *)arg)->y1 = 0;
}
return 1;
case U8G_DEV_MSG_SET_PIXEL:
case U8G_DEV_MSG_SET_8PIXEL:
if ( u8g_vs_current < u8g_vs_cnt )
{
((u8g_dev_arg_pixel_t *)arg)->x -= u8g_vs_list[u8g_vs_current].x;
((u8g_dev_arg_pixel_t *)arg)->y -= u8g_vs_list[u8g_vs_current].y;
return u8g_call_dev_fn(u8g_vs_list[u8g_vs_current].u8g, u8g_vs_list[u8g_vs_current].u8g->dev, msg, arg);
}
break;
}
return 1;
}
u8g_dev_t u8g_dev_vs = { u8g_dev_vs_fn, NULL, NULL };
void u8g_SetVirtualScreenDimension(u8g_t *vs_u8g, u8g_uint_t width, u8g_uint_t height)
{
if ( vs_u8g->dev != &u8g_dev_vs )
return; /* abort if there is no a virtual screen device */
u8g_vs_width = width;
u8g_vs_height = height;
}
uint8_t u8g_AddToVirtualScreen(u8g_t *vs_u8g, u8g_uint_t x, u8g_uint_t y, u8g_t *child_u8g)
{
if ( vs_u8g->dev != &u8g_dev_vs )
return 0; /* abort if there is no a virtual screen device */
if ( u8g_vs_cnt >= U8g_VS_MAX )
return 0; /* maximum number of child u8g's reached */
u8g_vs_list[u8g_vs_cnt].u8g = child_u8g;
u8g_vs_list[u8g_vs_cnt].x = x;
u8g_vs_list[u8g_vs_cnt].y = y;
u8g_vs_cnt++;
return 1;
}
......@@ -12,7 +12,7 @@
# a generated lib/image xxx.a ()
#
ifndef PDIR
GEN_LIBS = ucglib.a
GEN_LIBS = libucglib.a
endif
STD_CFLAGS=-std=gnu11 -Wimplicit
......
......@@ -40,7 +40,6 @@
static exception_handler_fn load_store_handler;
void load_non_32_wide_handler (struct exception_frame *ef, uint32_t cause)
{
/* If this is not EXCCAUSE_LOAD_STORE_ERROR you're doing it wrong! */
......@@ -73,13 +72,15 @@ void load_non_32_wide_handler (struct exception_frame *ef, uint32_t cause)
{
die:
/* Turns out we couldn't fix this, so try and chain to the handler
* that was set by the SDK. If none then trigger a system break instead
* and hang if the break doesn't get handled. This is effectively
* what would happen if the default handler was installed. */
* that was set. (This is typically a remote GDB break). If none
* then trigger a system break instead and hang if the break doesn't
* get handled. This is effectively what would happen if the default
* handler was installed. */
if (load_store_handler) {
load_store_handler(ef, cause);
return;
}
asm ("break 1, 1");
asm ("break 1, 1");
while (1) {}
}
......
......@@ -129,8 +129,7 @@ bool user_process_input(bool force) {
return task_post_low(input_sig, force);
}
void nodemcu_init(void)
{
void nodemcu_init(void) {
NODE_ERR("\n");
// Initialize platform first for lua modules.
if( platform_init() != PLATFORM_OK )
......@@ -139,11 +138,13 @@ void nodemcu_init(void)
NODE_DBG("Can not init platform for modules.\n");
return;
}
if( flash_detect_size_byte() != flash_rom_get_size_byte() ) {
NODE_ERR("Self adjust flash size.\n");
uint32_t size_detected = flash_detect_size_byte();
uint32_t size_from_rom = flash_rom_get_size_byte();
if( size_detected != size_from_rom ) {
NODE_ERR("Self adjust flash size. 0x%x (ROM) -> 0x%x (Detected)\n",
size_from_rom, size_detected);
// Fit hardware real flash size.
flash_rom_set_size_byte(flash_detect_size_byte());
flash_rom_set_size_byte(size_detected);
system_restart ();
// Don't post the start_lua task, we're about to reboot...
......@@ -260,6 +261,5 @@ void user_init(void)
#ifndef NODE_DEBUG
system_set_os_print(0);
#endif
system_init_done_cb(nodemcu_init);
}
......@@ -11,6 +11,13 @@ Occasional NodeMCU firmware hackers don't need full control over the complete to
### Linux Build Environment
NodeMCU firmware developers commit or contribute to the project on GitHub and might want to build their own full fledged build environment with the complete tool chain. There is a [post in the esp8266.com Wiki](http://www.esp8266.com/wiki/doku.php?id=toolchain#how_to_setup_a_vm_to_host_your_toolchain) that describes this.
### Git
If you decide to build with either the Docker image or the native environment then use Git to clone the firmware sources instead of downloading the ZIP file from GitHub. Only cloning with Git will retrieve the referenced submodules:
```
git clone --recurse-submodules -b <branch> https://github.com/nodemcu/nodemcu-firmware.git
```
Omitting the optional `-b <branch>` will clone master.
## Build Options
The following sections explain some of the options you have if you want to build your own NodeMCU firmware.
......@@ -24,7 +31,6 @@ Edit `app/include/user_modules.h` and comment-out the `#define` statement for mo
...
#define LUA_USE_MODULES_MQTT
// #define LUA_USE_MODULES_COAP
// #define LUA_USE_MODULES_U8G
...
```
......@@ -44,6 +50,9 @@ To enable runtime debug messages to serial console edit `app/include/user_config
#define DEVELOP_VERSION
```
### LFS
LFS is turned off by default. See the [LFS documentation](./lfs.md) for supported config options (e.g. how to enable it).
### Set UART Bit Rate
The initial baud rate at boot time is 115200bps. You can change this by
editing `BIT_RATE_DEFAULT` in `app/include/user_config.h`:
......@@ -81,8 +90,8 @@ Identify your firmware builds by editing `app/include/user_version.h`
#endif
```
### u8g Module Configuration
Display drivers and embedded fonts are compiled into the firmware image based on the settings in `app/include/u8g_config.h`. See the [`u8g` documentation](modules/u8g.md#displays) for details.
### u8g2 Module Configuration
Display drivers and embedded fonts are compiled into the firmware image based on the settings in `app/include/u8g2_displays.h` and `app/include/u8g2_fonts.h`. See the [`u8g2` documentation](modules/u8g2.md#displays) for details.
### ucg Module Configuration
Display drivers and embedded fonts are compiled into the firmware image based on the settings in `app/include/ucg_config.h`. See the [`ucg` documentation](modules/ucg.md#displays) for details.
# NodeMCU Documentation
NodeMCU is an [eLua](http://www.eluaproject.net/) based firmware for the [ESP8266 WiFi SOC from Espressif](http://espressif.com/en/products/esp8266/). The firmware is based on the Espressif NON-OS SDK and uses a file system based on [spiffs](https://github.com/pellepl/spiffs). The code repository consists of 98.1% C-code that glues the thin Lua veneer to the SDK.
NodeMCU is an open source [Lua](https://www.lua.org/) based firmware for the [ESP8266 WiFi SOC from Espressif](http://espressif.com/en/products/esp8266/) and uses an on-module flash-based [SPIFFS](https://github.com/pellepl/spiffs) file system. NodeMCU is implemented in C and is layered on the [Espressif NON-OS SDK](https://github.com/espressif/ESP8266_NONOS_SDK).
The NodeMCU *firmware* is a companion project to the popular [NodeMCU dev kits](https://github.com/nodemcu/nodemcu-devkit-v1.0), ready-made open source development boards with ESP8266-12E chips.
The firmware was initially developed as is a companion project to the popular ESP8266-based [NodeMCU development modules](https://github.com/nodemcu/nodemcu-devkit-v1.0), but the project is now community-supported, and the firmware can now be run on _any_ ESP module.
## Programming Model
The NodeMCU programming model is similar to that of [Node.js](https://en.wikipedia.org/wiki/Node.js), only in Lua. It is asynchronous and event-driven. Many functions, therefore, have parameters for callback functions. To give you an idea what a NodeMCU program looks like study the short snippets below. For more extensive examples have a look at the `/lua_examples` folder in the repository on GitHub.
......@@ -42,6 +42,8 @@ gpio.mode(pin, gpio.OUTPUT)
gpio.write(pin, gpio.HIGH)
print(gpio.read(pin))
```
### Lua Flash Store (LFS)
In July 2018 support for a [Lua Flash Store (LFS)](lfs.md) was introduced. LFS allows Lua code and its associated constant data to be executed directly out of flash-memory; just as the firmware itself is executed. This now enables NodeMCU developers to create Lua applications with up to 256Kb Lua code and read-only constants executing out of flash. All of the RAM is available for read-write data!
## Getting Started
1. [Build the firmware](build.md) with the modules you need.
......
## Lua Compact Debug (LCD)
LCD (Lua Compact Debug) was developed in Sept 2015 by Terry Ellison as a patch to the Lua system to decrease the RAM usage of Lua scripts. This makes it possible to run larger Lua scripts on systems with limited RAM. Its use is most typically for eLua-type applications, and in this version it targets the **NodeMCU** implementation for the ESP8266 chipsets.
This section gives a full description of LCD. If you are writing **NodeMCU** Lua modules, then this paper will be of interest to you, as it shows how to use LCD in an easy to configure way. *Note that the default `user_config.h` has enabled LCD at a level 2 stripdebug since mid-2016*.
### Motivation
The main issue that led me to write this patch is the relatively high Lua memory consumption of its embedded debug information, as this typically results in a 60% memory increase for most Lua code. This information is generated when any Lua source is complied because the Lua parser uses this as meta information during the compilation process. It is then retained by default for use in generating debug information. The only standard method of removing this information is to use the “strip” option when precompiling source using a standard eLua **luac.cross** on the host, or (in the case of NodeMCU) using the `node.compile()` function on the target environment.
Most application developers that are new to embedded development simply live with this overhead, because either they aren't familiar with these advanced techniques, or they want to keep the source line information in error messages for debugging.
The standard Lua compiler generates fixed 4 byte instructions which are interpreted by the Lua VM during execution. The debug information consists of a map from instruction count to source line number (4 bytes per instruction) and two tables keyed by the names of each local and upvalue. These tables contain metadata on these variables used in the function. This information can be accessed to enable symbolic debugging of Lua source (which isn't supported on **NodeMCU** platforms anyway), and the line number information is also used to generate error messages.
This overhead is sufficient large on limited RAM systems to replace this scheme by making two changes which optimize for space rather than time:
- The encoding scheme used in this patch typically uses 1 byte per source line instead of 4 bytes per instruction, and this represents a 10 to 20-fold reduction in the size of this vector. The access time during compile is still **O(1)**, and **O(N)** during runtime error handling, where **N** is number of non-blank lines in the function. In practice this might add a few microseconds to the time take to generate the error message for typical embedded functions.
- The line number, local and upvalue information is needed during the compilation of a given compilation unit (a source file or source string), but its only use after this is for debugging and so can be discarded. (This is what the `luac -s` option and `node.compile()` do). The line number information if available is used in error reporting. An extra API call has therefore been added to discarded this debug information on completion of the compilation.
To minimise the impact within the C source code for the Lua system, an extra system define **LUA_OPTIMIZE_DEBUG** can be set in the `user_config.h` file to configure a given firmware build. This define sets the default value for all compiles and can take one of four values:
1. (or not defined) use the default Lua scheme.
2. Use compact line encoding scheme and retain all debug information.
3. Use compact line encoding scheme and only retain line number debug information.
4. Discard all debug information on completion of compile.
Building the firmware with the 0 option compiles to the pre-patch version. Options 1-3 generate the `strip_debug()` function, which allows this default value to be set at runtime.
_Note that options 2 and 3 can also change the default behaviour of the `loadstring()` function in that any functions declared within the string cannot inherited any outer locals within the parent hierarchy as upvalues if these have been stripped of the locals and upvalues information._
### Details
There are various API calls which compile and load Lua source code. During compilation each variable name is parsed, and is then resolved in the following order:
- Against the list of local variables declared so far in the current scope is scanned for a match.
- Against the local variable lists for each of the lexically parent functions are then scanned for a match, and if found the variable is tagged as an _upvalue_.
- If unmatched against either of these local scopes then the variable defaults to being a global reference.
The parser and code generator must therefore access the line mapping, upvalues, and locals information tables maintained in each function Prototype header during source compilation. This scoping scheme works because function compilation is recursive: if function A contains the definition of function B which contains the definition of function C, then the compilation of A is paused to compile B and this is in turn paused to compile C; then B complete and then A completes.
The variable meta information is stored in standard Lua tables which are allocated using the standard Lua doubling algorithm and hence they can contain a lot of unused space. The parser therefore calls `close_func()` once compilation of a function has been completed to trim these vectors to the final sizes.
The patch makes the following if `LUA_OPTIMIZE_DEBUG` > 0. (The existing functionality is preserved if this define is zero or undefined.)
- It adds an extra API call: `stripdebug([level[, function]])` as discussed below.
- It extends the trim logic in `close_func()` to replace this trim action by deleting the information according to the current default debug optimization level.
- The `lineinfo` vector associated with each function is replaced by a `packedlineinfo` string using a run length encoding scheme that uses a repeat of an optional line number delta (this is omitted if the line offset is zero) and a count of the number of instruction generated for that source line. This scheme uses roughly an **M** byte vector where **M** is the number of non-blank source lines, as opposed to a **4N** byte vector where **N** is the number of VM instruction. This vector is built sequentially during code generation so it is this patch conditionally replaces the current map with an algorithm to generate the packed version on the fly.
The `stripdebug([level[, function]])` call is processed as follows:
- If both arguments are omitted then the function returns the current default strip level.
- If the function parameter is omitted, then the level is used as the default setting for future compiles. The level must be 1-3 corresponding to the above debug optimization settings. Hence if `stripdebug(3)` is included in **init.lua**, then all debug information will be stripped out of subsequently compiled functions.
- The function parameter if present is parsed in the same way as the function argument in `setfenv()` (except that the integer 0 level is not permitted, and this function tree corresponding to this scope is walked to implement this debug optimization level.
The `packedlineinfo` encoding scheme is as follows:
- It comprises a repeat of (optional) line delta + VM instruction count (IC) for that line starting from a base line number of zero. The line deltas are optional because line deltas of +1 are assumed as default and therefore not emitted.
- ICs are stored as a single byte with the high bit set to zero. Sequences longer than 126 instructions for a single sequence are rare, but can be are encoded using a multi byte sequence using 0 line deltas, e.g. 126 (0) 24 for a line generating 150 VM instructions. The high bit is always unset, and note that this scheme reserves the code 0x7F as discussed below.
- Line deltas are stored with the high bit set and are variable (little-endian) in length. Since deltas are always delimited by an IC which has the top bit unset, the length of each delta can be determined from these delimiters. Deltas are stored as signed ones-compliment with the sign bit in the second bit of low order byte, that is in the format (in binary) `1snnnnnnn [1nnnnnnn]*`, with `s` denoting the sign and `n…n` the value element using the following map. This means that a single byte is used encode line deltas in the range -63 … 65; two bytes used to encode line deltas in the range -8191 … 8193, etc..
```C
value = (sign == 1) ? -delta : delta - 2
```
- This approach has no arbitrary limits, in that it can accommodate any line delta or IC count. Though in practice, most deltas are omitted and multi-byte sequences are rarely generated.
- The codes 0x00 and 0x7F are reserved in this scheme. This is because Lua allocates such growing vectors on a size-doubling basis. The line info vector is always null terminated so that the standard **strlen()** function can be used to determine its length. Any unused bytes between the last IC and the terminating null are filled with 0x7F.
The current mapping scheme has **O(1)** access, but with a code-space overhead of some 140%. This alternative approach has been designed to be space optimized rather than time optimized. It requires the actual IC to line number map to be computed by linearly enumerating the string from the low instruction end during execution, resulting in an **O(N)** access cost, where **N** is the number of bytes in the encoded vector. However, code generation builds this information incrementally, and so only appends to it (or occasionally updates the last element's line number), and the patch adds a couple of fields to the parser `FuncState` record to enable efficient **O(1)** access during compilation.
### Testing
Essentially testing any eLua compiler or runtime changes are a total pain, because eLua is designed to be build against a **newlib**-based ELF. Newlib uses a stripped down set of headers and libraries that are intended for embedded use (rather than being ran over a standard operating system). Gdb support is effectively non-existent, so I found it just easier first to develop this code on a standard Lua build running under Linux (and therefore with full gdb support), and then port the patch to NodeMCU once tested and working.
I tested my patch in standard Lua built with "make generic" and against the [Lua 5.1 suite](http://lua-users.org/lists/lua-l/2006-03/msg00723.html). The test suite was an excellent testing tool, and it revealed a number of cases that exposed logic flaws in my approach, resulting from Lua's approach of not carrying out inline status testing by instead implementing a throw / catch strategy. In fact I realised that I had to redesign the vector generation algorithm to handle this robustly.
As with all eLua builds the patch assumes Lua will not be executing in a multithreaded environment with OS threads running different lua_States. (This is also the case for the NodeMCU firmware). It executes the full test suite cleanly as maximum test levels and I also added some specific tests to cover new **stripdebug** usecases.
Once this testing was completed, I then ported the patch to the NodeMCU build. This was pretty straight forward as this code is essentially independent of the NodeMCU functional changes. The only real issue as to ensure that the NodeMCU `c_strlen()` calls replaced the standard `strlen()`, etc.
I then built both `luac.cross` and firmware images with the patch disable to ensure binary compatibility with the non-patched version and then with the patch enabled at optimization level 3.
In use there is little noticeable difference other than the code size during development are pretty much the same as when running with `node.compile()` stripped code. The new option 2 (retaining packed line info only) has such a minimal size impact that its worth using this all the time. I've also added a separate patch to NodeMCU (which this assumes) so that errors now generate a full traceback.
### How to enable LCD
Enabling LCD is simple: all you need is a patched version and define `LUA_OPTIMIZE_DEBUG` at the default level that you want in `app/include/user_config.h` and do a normal make.
Without this define enabled, the unpatched version is generated.
Note that since `node.compile()` strips all debug information, old **.lc** files generated by this command will still run under the patched firmware, but binary files which retain debug information will not work across patched and non-patched versions.
Other than optionally including a `node.stripdebug(N)` or whatever in your **init.lua**, the patch is otherwise transparent at an application level.
# Lua Flash Store (LFS)
## Background
Lua was originally designed as a general purpose embedded extension language for use in applications run on a conventional computer such as a PC, where the processor is mounted on a motherboard together with multiple Gb of RAM and a lot of other chips providing CPU and I/O support to connect to other devices.
ESP8266 modules are on a very different scale: they cost a few dollars; they are postage stamp-sized and only mount two main components, an ESP [SoC](https://en.wikipedia.org/wiki/System_on_a_chip) and a flash memory chip. The SoC includes limited on-chip RAM, but also provides hardware support to map part of the external flash memory into a separate memory address region so that firmware can be executed directly out of this flash memory &mdash; a type of [modified Harvard architecture](https://en.wikipedia.org/wiki/Modified_Harvard_architecture) found on many [IoT](https://en.wikipedia.org/wiki/Internet_of_things) devices. Even so, Lua's design goals of speed, portability, small kernel size, extensibility and ease-of-use have made it a good choice for embedded use on an IoT platform, but with one major limitaton: the standard Lua core runtime system (**RTS**) assumes that both Lua data _and_ code are stored in RAM; this isn't a material constraint with a conventional computer, but it can be if your system only has some 48Kb RAM available for application use.
The Lua Flash Store (**LFS**) patch modifies the Lua RTS to support a modified Harvard architecture by allowing the Lua code and its associated constant data to be executed directly out of flash-memory (just as the NoceMCU firmware is itself executed). This now allows NodeMCU Lua developers to create Lua applications with up to 256Kb Lua code and read-only (**RO**) constants executing out of flash, with all of the RAM is available for read-write (**RW**) data.
Unfortunately, the ESP architecture provides very restricted write operations to flash memory (writing to NAND flash involves bulk erasing complete 4Kb memory pages, before overwriting each erased page with any new content). Whilst it is possible to develop a R/W file system within this constraint (as SPIFFS demonstrates), this makes impractical to modify Lua code pages on the fly. Hence the LFS patch works within a reflash-and-restart paradigm for reloading the LFS, and does this by adding two API new calls: one to reflash the LFS and restart the processor, and one to access LFS stored functions. The patch also addresses all of the technical issues 'under the hood' to make this magic happen.
The remainder of this paper is split into two parts. The first provides an overview for Lua developers wanting to use LFS effectively at an application programming level, and as most of our developers use a Windows platform, it gives a quick start for these developers before covering some of application issues in more detail. The second part is for those who want to understand a little of how this magic happens, and gives more details on the technical issues that were addressed in order to implement the patch.
## Using LFS
### A Quick Start for Windows Developers
This is a simple step-by-step guide for ESP8266 Lua developers who want to start to use `luac.cross` on a Windows development environment.
#### Get and flash LFS enabled firmware
Use the [NodeMCU Build](https://nodemcu-build.com/) service to build the firmware. In the "LFS options" section choose the size of the LFS partition (64 KB should be fine). The SPIFFS default settings will be fine. See section [selecting the firmware](#selecting-the-firmware) for further details. Once you have received the build confirmation email and downloaded the flash image, you can then [flash the firmware](flash.md) to your ESP8266.
#### Build or download your local copy of `luac.cross`
Windows 10 users can install and use the Windows Subsystem for Linux (WSL). Alternatively all Windows users can [install Cygwin](https://www.cygwin.com/install.html). (You will only need the Cygwin core). Either way, you will need a copy of the `luac.cross` compiler:
- You can either download this from my fileserver. The [ELF variant](http://files.ellisons.org.uk/esp8266/luac.cross) is used for all recent Linux and WSL flavours, or the [cygwin binary](http://files.ellisons.org.uk/esp8266/luac.cross.cygwin)) for the Cygwin environment.
- Or you can compile it yourself by downloading the current NodeMCU sources (this [ZIPfile](https://github.com/nodemcu/nodemcu-firmware/archive/master.zip)); edit the `app/includes/user_config.h` file and the `cd` to the `app/lua/luac_cross` and run make to build the compiler in the NodeMCU firmware root directory. Note that the `luac.cross` make only needs the host toolchain which is installed by default in WSL, but in Cygwin you will need to tick the _gcc-core_ + _gnu make_ options during setup.
#### Select Lua files to be run from LFS
The easiest approach is to maintain all the Lua files for your project in a single directory on your host. (These files will be compiled by `luac.cross` to build the LFS image in next step.)
For example to run the Telnet and FTP servers from LFS, put the following files in your project directory:
* [lua_examples/lfs/_init.lua](https://github.com/nodemcu/nodemcu-firmware/tree/dev/lua_examples/lfs/_init.lua). LFS helper routines and functions.
* [lua_examples/lfs/dummy_strings.lua](https://github.com/nodemcu/nodemcu-firmware/tree/dev/lua_examples/lfs/dummy_strings.lua). Moving common strings into LFS.
* [lua_examples/telnet/telnet.lua](https://github.com/nodemcu/nodemcu-firmware/tree/dev/lua_examples/telnet/telnet.lua). A simple **telnet** server.
* [lua_modules/ftp/ftpserver.lua](https://github.com/nodemcu/nodemcu-firmware/tree/dev/lua_modules/ftp/ftpserver.lua). A simple **FTP** server.
You should always include the first two modules, but the remaining files would normally be replaced by your own project files. Also remember that these are examples and that you are entirely free to modify or to replace them for your own application needs.
#### Compile the LFS image
You will do this from within the WSL or Cygwin command window, both of which use the `bash` shell; do a `cd` to the project directory, and execute the command:
```bash
luac.cross -o lfs.img -f *.lua
```
You will need to adjust the `img` and `lua` paths according to their location, and ensure that `luac.cross` is in your `$PATH` search list. For example if you are using WSL and your project files are in `D:\myproject` then the Lua path would be `/mnt/d/myproject/*.lua` (For cygwin replace `mnt` by `cygwin`). This will create the `lfs.img` file if there are no Lua compile errors (again specify an explicit directory path if needed).
You might also want to add a simple one-line script file to your ~/bin directory to wrap this command up.
#### Upload the LFS image and flash it to the LFS region
Now upload the compiled LFS image file (`lfs.img` in this case) as a normal SPIFFS file. Several tools are available to upload the files from host to SPIFFS, including [ESPlorer](https://github.com/4refr0nt/ESPlorer). There is also a new example, [HTTP_OTA.lua](https://github.com/nodemcu/nodemcu-firmware/tree/dev/lua_examples/lfs/HTTP_OTA.lua), in `lua_examples` that can retrieve images from a standard web service.
Once the LFS image file is on SPIFFS, you can execute the [node.flashreload()](/en/dev/en/modules/node/#nodeflashreload) command and the loader will then load it into flash and immediately restart the ESP module with the new LFS loaded, if the image file is valid. However, the call will return with an error _if_ the file is found to be invalid, so your reflash code should include logic to handle such an error return.
#### Edit your `init.lua` file
`init.lua` is the file that is first executed by the NodeMCU firmware. Usually it setups the WiFi connection and executes the main Lua application. Assuming that you have included the `_init` file discussed above, then executing this will add a simple API for LFS module access:
- Individual functions can be executed directly, e.g. `LFS.myfunc(a,b)`
- LFS is now in the require path, so `require 'myModule'` works as expected.
Do a protected call of this `_init` code: `pcall(node.flashindex("_init"))` and check the error status. See [Programming Techniques and Approachs](#programming-techniques-and-approachs) below for a more detailed description.
The remainder of this section describes how to use LFS in further detail.
### Selecting the firmware
Power developers might want to use Docker or their own build environment as per our [Building the firmware](https://nodemcu.readthedocs.io/en/master/en/build/) documentation, and so `app/include/user_config.h` has now been updated to include the necessary documentation on how to select the configuration options to make an LFS firmware build.
However, most Lua developers seem to prefer the convenience of our [Cloud Build Service](https://nodemcu-build.com/), so we have added extra LFS menu options to facilitate building LFS images:
Variable | Option
---------|------------
LFS size | (none, 32, 64, 96 or 128Kb) The default is none. The default is none, in which case LFS is disabled. Selecting a numeric value enables LFS with the LFS region sized at this value.
SPIFFS base | If you have a 4Mb flash module then I suggest you choose the 1024Kb option as this will preserve the SPIFFS even if you reflash with a larger firmware image; otherwise leave this at the default 0.
SPIFFS size | (default or various multiples of 64Kb) Choose the size that you need. Larger FS require more time to format on first boot.
You must choose an explicit (non-default) LFS size to enable the use of LFS. Most developers find it more useful to work with a fixed SPIFFS size matched to their application requirements.
### Choosing your development life-cycle
The build environment for generating the firmware images is Linux-based, but you can still develop NodeMCU applications on pretty much any platform including Windows and MacOS, as you can use our cloud build service to generate these images. Unfortunately LFS images must be built off-ESP on a host platform, so you must be able to run the `luac.cross` cross compiler on your development machine to build LFS images.
- For Windows 10 developers, one method of achieving this is to install the [Windows Subsystem for Linux](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux). The default installation uses the GNU `bash` shell and includes the core GNU utilities. WSL extends the NT kernel to support the direct execution of Linux ELF images, and it can directly run the `luac.cross` and `spiffsimg` that are build as part of the firmware. You will also need the `esptool.py` tool but `python.org` already provides Python releases for Windows. Of course all Windows developers can use the Cygwin environment as this runs on all Windows versions and it also takes up less than ½Gb HDD (WSL takes up around 5Gb).
- Linux users can just use these tools natively. Windows users can also to do this in a linux VM or use our standard Docker image. Another alternaive is to get yourself a Raspberry Pi or equivalent SBC and use a package like [DietPi](http://www.dietpi.com/) which makes it easy to install the OS, a Webserver and Samba and make the RPi look like a NAS to your PC. It is also straightforward to write a script to automatically recompile a Samba folder after updates and to make the LFS image available on the webservice so that your ESP modules can update themselves OTA using the new `HTTP_OTA.lua` example.
- In principle, only the environment component needed to support applicatin development is `luac.cross`, built by the `app/lua/lua_cross` make. (Some developers might also use the `spiffsimg` exectable, made in the `tools/spifsimg` subdirectory). Both of these components use the host toolchain (that is the compiler and associated utilities), rather than the Xtensa cross-compiler toolchain, so it is therefore straightforward to make under any environment which provides POSIX runtime support, including WSL, MacOS and Cygwin.
Most Lua developers seem to start with the [ESPlorer](https://github.com/4refr0nt/ESPlorer) tool, a 'simple to use' IDE that enables beginning Lua developers to get started. ESPlorer can be slow cumbersome for larger ESP application, and it requires a direct UART connection. So many experienced Lua developers switch to a rapid development cycle where they use a development machine to maintain your master Lua source. Going this route will allow you use your favourite program editor and source control, with one of various techniques for compiling the lua on-host and downloading the compiled code to the ESP:
- If you use a fixed SPIFFS image (I find 128Kb is enough for most of my applications) and are developing on a UART-attached ESP module, then you can also recompile any LC files and LFS image, then rebuild a SPIFFS file system image before loading it onto the ESP using `esptool.py`; if you script this you will find that this cycle takes less than a minute. You can either embed the LFS.img in the SPIFFS. You can also use the `luac.cross -a` option to build an absolute address format image that you can directly flash into the LFS region within the firmware.
- If you only need to update the Lua components, then you can work over-the-air (OTA). For example see my
[HTTP_OTA.lua](https://github.com/nodemcu/nodemcu-firmware/tree/dev/lua_examples/lfs/HTTP_OTA.lua), which pulls a new LFS image from a webservice and reloads it into the LFS region. This only takes seconds, so I often use this in preference to UART-attached loading.
- Another option would be to include the FTP and Telnet modules in the base LFS image and to use telnet and FTP to update your system. (Given that a 64Kb LFS can store thousands of lines of Lua, doing this isn't much of an issue.)
My current practice is to use a small bootstrap `init.lua` file in SPIFFS to connect to WiFi, and also load the `_init` module from LFS to do all of the actual application initialisation. There is a few sec delay whilst connecting to the Wifi, and this delay also acts as a "just in case" when I am developing, as it is enough to allow me to paste a `file.remove('init.lua')` into the UART if my test applicaiton is stuck into a panic loop, or set up a different development path for debugging.
Under rare circumstances, for example a power fail during the flashing process, the flash can be left in a part-written state following a `flashreload()`. The Lua RTS start-up sequence will detect this and take the failsafe opton of resetting the LFS to empty, and if this happens then the LFS `_init` function will be unavailable. Your `init.lua` should therefore not assume that the LFS contains any modules (such as `_init`), and should contain logic to detect if LFS reset has occurred and if necessary reload the LFS again. Calling `node.flashindex("_init")()` directly will result in a panic loop in these circumstances. Therefore first check that `node.flashindex("_init")` returns a function or protect the call, `pcall(node.flashindex("_init"))`, and decode the error status to validate that initialisation was successful.
No doubt some standard usecase / templates will be developed by the community over the next six months.
### Programming Techniques and approachs
I have found that moving code into LFS has changed my coding style, as I tend to use larger modules and I don't worry about in-memory code size. This make it a lot easier to adopt a clearer coding style, so my ESP Lua code now looks more similar to host-based Lua code. Lua code can still be loaded from SPIFFS, so you still have the option to keep code under test in SPIFFS, and only move modules into LFS once they are stable.
#### Accessing LFS functions and loading LFS modules
See [lua_examples/lfs/_init.lua](https://github.com/nodemcu/nodemcu-firmware/tree/dev/lua_examples/lfs/_init.lua) for the code that I use in my `_init` module to do create a simple access API for LFS. There are two parts to this.
The first sets up a table in the global variable `LFS` with the `__index` and `__newindex` metamethods. The main purpose of the `__index()` is to resolve any names against the LFS using a `node.flashindex()` call, so that `LFS.someFunc(params)` does exactly what you would expect it to do: this will call `someFunc` with the specified parameters, if it exists in in the LFS. The LFS properties `_time`, `_config` and `_list` can be used to access the other LFS metadata that you need. See the code to understand what they do, but `LFS._list` is the array of all module names in the LFS. The `__newindex` method makes `LFS` readonly.
The second part uses standard Lua functionality to add the LFS to the require [package.loaders](http://pgl.yoyo.org/luai/i/package.loaders) list. (Read the link if you want more detail). There are four standard loaders, which the require loader searches in turn. NodeMCU only uses the second of these (the Lua loader from the file system), and since loaders 1,3 and 4 aren't used, we can simply replace the 1st or the 3rd by code to use `node.flashindex()` to return the LFS module. The supplied `_init` puts the LFS loader at entry 3, so if the module is in both SPIFFS and LFS, then the SPIFFS version will be loaded. One result of this has burnt me during development: if there is an out of date version in SPIFFS, then it will still get loaded instead of the one if LFS.
If you want to swap this search order so that the LFS is searched first, then SET `package.loaders[1] = loader_flash` in your `_init` code. If you need to swap the search order temporarily for development or debugging, then do this after you've run the `_init` code:
```Lua
do local pl = package.loaders; pl[1],pl[3] = pl[3],pl[1]; end
```
#### Moving common string constants into LFS
LFS is mainly used to store compiled modules, but it also includes its own string table and any strings loaded into this can be used in your Lua application without taking any space in RAM. Hence, you might also want to preload any other frequently used strings into LFS as this will both save RAM use and reduced the Lua Garbage Collector (**LGC**) overheads.
The new debug function `debug.getstrings()` can help you determine what strings are worth adding to LFS. It takes an optional string argument `'RAM'` (the default) or `'ROM'`, and returns a list of the strings in the corresponding table. So the following example can be used to get a listing of the strings in RAM.
```Lua
do
local a=debug.getstrings'RAM'
for i =1, #a do a[i] = ('%q'):format(a[i]) end
print ('local preload='..table.concat(a,','))
end
```
You can do this at the interactive prompt or call it as a debug function during a running application in order to generate this string list, (but note that calling this still creates the overhead of an array in RAM, so you do need to have enough "head room" to do the call).
You can then create a file, say `LFS_dummy_strings.lua`, and insert these `local preload` lines into it. By including this file in your `luac.cross` compile, then the cross compiler will also include all strings referenced in this dummy module in the generated ROM string table. Note that you don''t need to call this module; it's inclusion in the LFS build is enough to add the strings to the ROM table. Once in the ROM table, then you can use them subsequently in your application without incurring any RAM or LGC overhead.
A useful starting point may be found in [lua_examples/lfs/dummy_strings.lua](https://github.com/nodemcu/nodemcu-firmware/tree/dev/lua_examples/lfs/dummy_strings.lua); this saves about 4Kb of RAM by moving a lot of common compiler and Lua VM strings into ROM.
Another good use of this technique is when you have resources such as CSS, HTML and JS fragments that you want to output over the internet. Instead of having lots of small resource files, you can just use string assignments in an LFS module and this will keep these constants in LFS instead.
## Technical issues
Whilst memory capacity isn't a material constraint on most conventional machines, the Lua RTS still includes some features to minimise overall memory usage. In particular:
- The more resource intensive data types are know as _collectable objects_, and the RTS includes a LGC which regularly scans these collectable resources to determine which are no longer in use, so that their associated memory can be reclaimed and reused.
- The Lua RTS also treats strings and compiled function code as collectable objects, so that these can also be LGCed when no longer referenced
The compiled code, as executed by Lua RTS, internally comprises one or more function prototypes (which use a `Proto` structure type) plus their associated vectors (constants, instructions and meta data for debug). Most of these compiled constant types are basic (e.g. numbers) and the only collectable constant data type are strings. The other collectable types such as arrays are actually created at runtime by executing Lua compiled instructions to build each resource dynamically.
When any Lua file is loaded without LFS into an ESP application, the RTS loads the corresponding compiled version into RAM. Each compiled function has its own Proto structure hierarchy, but this hierarchy is not exposed directly to the running application; instead the compiler generates `CLOSURE` instruction which is executed at runtime to bind the `Proto` to a Lua function value thus creating a [closure](https://en.wikipedia.org/wiki/Closure_(computer_programming)). Since this occurs at runtime, any `Proto` can be bound to multiple closures. A Lua closure can also have multiple RW [Upvalues](https://www.lua.org/pil/27.3.3.html) bound to it, and so function value is a Lua RW object in that it is referring to something that can contain RW state, even though the `Proto` hierarchy itself is intrinsically RO.
Whilst advanced ESP Lua programmers can use overlay techniques to ensure that only active functions are loaded into RAM and thus increase the effective application size, this adds to runtime and program complexity. Moving Lua "program" resources into ESP Flash addressable memory typically at least doubles the effective RAM available, and removes the need to complicate applications code by implementing overlaying.
Any RO resources that are relocated to a flash address space:
- Must not be collected. Also RW references to RO resources must be robustly handled by the LGC.
- Cannot reference to any volatile RW data elements (though RW resources can refer to RO resources).
All strings in Lua are [interned](https://en.wikipedia.org/wiki/String_interning), so that only one copy of any string is kept in memory, and most string manipulation uses the address of this single copy as a unique reference. This uniqueness and the LGC of strings is facilitated by using a global string table that is hooked into the Lua global state. Within standard Lua VM, any new string is first resolved against RAM string table, so that only the string-misses are added to the string table.
The LFS patch adds a second RO string table in flash and this contains all strings used in the LFS Protos. Maintaining integrity across the two string tables is simple and low-cost, with LFS resolution process extended across both the RAM and ROM string tables. Hence any strings already in the ROM string table already have a unique string reference avoiding the need to add an additional entry in the RAM table. This both significantly reduces the size of the RAM string table, and removes a lot of strings from the LCG scanning.
Note that my early development implementations of the LFS build process allowed on-target ESP builds, but I found that the Lua compiler was too resource hungry for usable application sizes, and it was impractical to get this approach to scale. So we abandoned this approach and moved the LFS build process onto the development host machine by embedding this into `luac.cross`. This approach also avoids all of the update integrity issues involved in building a new LFS which might require RO resources already referenced in the RW ones.
A LFS image can be loaded in the LFS store by one of two mechanisms:
- The image can be build on the host and then copied into SPIFFS. Calling the `node.flashreload()` API with this filename will load the image, and then schedule a restart to leave the ESP in normal application mode, but with an updated flash block. This sequence is essentially atomic. Once called, and the format of the LFS image has been valiated, then the only exit is the reboot.
- The second option is to build the LFS image using the `-a` option to base it at the correct absolute address of the LFS store for a given firmware image. The LFS can then be flashed to the ESP along with the firmware image.
The LFS store is a fixed size for any given firmware build (configurable by the a pplication developer through `user_config.h`) and is at a build-specific base address within the `ICACHE_FLASH` address space. This is used to store the ROM string table and the set of `Proto` hierarchies corresponding to a list of Lua files in the loaded image.
A separate `node.flashindex()` function creates a new Lua closure based on a module loaded into LFS and more specfically its flash-based prototype; whilst this access function is not transparent at a coding level, this is no different functionally than already having to handle `lua` and `lc` files and the existing range of load functions (`load`,`loadfile`, `loadstring`). Either way, creating a closure on flash-based prototype is _fast_ in terms of runtime. (It is basically a single instruction rather than a compile, and it has minimal RAM impact.)
### Implementation details
This **LFS** patch uses two string tables: the standard Lua RAM-based table (`RWstrt`) and a second RO flash-based one (`ROstrt`). The `RWstrt` is searched first when resolving new string requests, and then the `ROstrt`. Any string not already in either table is then added to the `RWstrt`, so this means that the RAM-based string table only contains application strings that are not already defined in the `ROstrt`.
Any Lua file compiled into the LFS image includes its main function prototype and all the child resources that are linked in its `Proto` structure; so all of these resources are compiled into the LFS image with this entire hierarchy self-consistently within the flash memory.
```C
TValue *k; Constants used by the function
Instruction *code The Lua VM instuction codes
struct Proto **p; Functions defined inside the function
int *lineinfo; Debug map from opcodes to source lines
struct LocVar *locvars; Debug information about local variables
TString **upvalues Debug information about upvalue names
TString *source String name associated with source file
```
Such LFS images are created by `luac.cross` using the `-f` option, and this builds a flash image using the list of modules provided but with a master "main" function of the form:
```Lua
local n = ...,1518283691 -- The Unix Time of the compile
if n == "module1" then return module1 end
if n == "module2" then return module2 end
-- and so on
if n == "moduleN" then return module2 end
return 1518283691,"module1","module2", --[[ ... ]] ""moduleN"
```
Note that you can't actually code this Lua because the modules are in separate compilation units, but the compiler being a compiler can just emit the compiled code directly. (See `app/lua/luac_cross/luac.c` for the details.)
The deep cross-copy of the compiled `Proto` hierarchy is also complicated because current hosts are typically 64bit whereas the ESPs are 32bit, so the structures need repacking. (See `app/lua/luac_cross/luac.c` for the details.)
This patch moves the `luac.cross` build into the overall application make hierarchy and so it is now simply a part of the NodeMCU make. The old Lua script has been removed from the `tools` directory, together with the need to have Lua pre-installed on the host.
The LFS image is by default position independent, so is independent of the actual NodeMCU target image. You just have to copy it to the target file system and execute a `flashreload` and this copies the image from SPIFSS to the correct flash location, relocating all address to the correct base. (See `app/lua/lflash.c` for the details.) This process is fast.
A `luac.cross -a` option also allows absolute address images to be built for direct flashing the LFS store onto the module during provisioning.
### Impact of the Lua Garbage Collector
The LGC applies to what the Lua VM classifies as collectable objects (strings, tables, functions, userdata, threads -- known collectively as `GCObjects`). A simple two "colour" LGC was used in previous Lua versions, but Lua 5.1 introduced the Dijkstra's 3-colour (*white*, *grey*, *black*) variant that enabled the LGC to operate in an incremental mode. This permits smaller LGC steps interspersed by LGC pause, and is very useful for larger scale Lua implementations. Whilst this is probably not really needed for IoT devices, NodeMCU follows this standard Lua 5.1 implementation, albeit with the `elua` EGC changes.
In fact, two *white* flavours are used to support incremental working (so this 3-colour algorithm really uses 4). All newly allocated collectable objects are marked as the current *white*, and a link in `GCObject` header enables scanning through all such Lua objects. Collectable objects can be referenced directly or indirectly via one of the Lua application's *roots*: the global environment, the Lua registry and the stack.
The standard LGC algorithm is quite complex and assumes that all GCObjects are RW so that a flag byte within each object can be updated during the mark and sweep processing. LFS introduces GCObjects that are stored in RO memory and are therefore truly RO.
The LFS patch therefore modifies the LGC processing to avoid such updates to GCObjects in RO memory, whilst still maintaining overall object integrity, as any attempt to update their content during LGC will result in the firmware crashing with a memory exception; the remainder of this section provides further detail on how this was achieved. The LGC operates two broad phases: **mark** and **sweep**
- The **mark** phase walks collectable objects by a recursive walk starting at at the LGC roots. (This is referred to as _traverse_.) Any object that is visited in this walk has its colour flipped from *white* to *grey* to denote that it is in use, and it is relinked into a grey list. The grey list is iteratively processed, removing one grey object at a time. Such objects can reference other objects (e.g. a table has many keys and values which can also be collectable objects), so each one is then also traversed and all objects reachable from it are marked, as above. After an object has been traversed, it's turned from grey to black. The LGC will walks all RW collectable objects, traversing the dependents of each in turn. As RW objects can now refer to RO ones, the traverse routines has additinal tests to skip trying to mark any RO LFS references.
- The white flavour is flipped just before entering the **sweep** phase. This phase then loops over all collectable objects. Any objects found with previous white are no longer in use, and so can be freed. The 'current' white are kept; this prevents any new objects created during a paused sweep from being accidentally collected before being marked, but this means that it takes two sweeps to free all unused objects. There are other subtleties introduced in this 3-colour algorithm such as barriers and back-tracking to maintain integrity of the LGC, and these also needed extra rules to handle RO GCObjects correclty, but detailed explanation of these is really outside the scope of this paper.
As well as standard collectable GCOobjets:
- Standard Lua has the concept of **fixed** objects. (E.g. the main thread). These won't be collected by the LGC, but they may refer to objects that aren't fixed, so the LGC still has to walk through an fixed objects.
- eLua added the the concept of **readonly** objects, which confusingly are a hybrid RW/RO implementation, where the underlying string resource is stored as a program constant in flash memory but the `TSstring` structure which points to this is still kept in RAM and can by GCed, except that in this case the LGC does not free the RO string constant itself.
- LFS introduces a third variant **flash** object for `LUA_TPROTO` and `LUA_TSTRING` types. Flash objects can only refer to other flash objects and are entirely located in the LFS area in flash memory.
The LGC already processed the _fixed_ and _readonly_ object, albeit as special cases. In the case of _flash_ GCObjects, the `mark` flag is in read-only memory and therefore the LGC clearly can't use this as a RW flag in its mark and sweep processing. So the LGC skips any marking operations for flash objects. Likewise, where all other GCObjects are linked into one of a number of sweeplists using the object's `gclist` field. In the case of flash objects, the compiler presets the `mark` and `gclist` fields with the fixed and readonly mark bits set, and the list pointer to `NULL` during the compile process.
As far as the LGC algorithm is concerned, encountering any _flash_ object in a sweep is a dead end, so that branch of the walk of the GCObject hierarchy can be terminated on encountering a flash object. This in practice all _flash_ objects are entirely removed from the LGC process, without compromising collection of RW resources.
### General comments
- **Reboot implementation**. Whilst the application initiated LFS reload might seem an overhead, it typically only adds a few seconds per reboot.
- **LGC reduction**. Since the cost of LGC is directly related to the size of the LGC sweep lists, moving RO resources into LFS memory removes them from the LGC scope and therefore reduces LGC runtime accordingly.
- **Typical Usecase**. The rebuilding of a store is an occasional step in the development cycle. (Say up to 10-20 times a day in a typical intensive development process). Modules and source files under development can also be executed from SPIFFS in `.lua` format. The developer is free to reorder the `package.loaders` and load any SPIFFS files in preference to Flash ones. And if stable code is moved into Flash, then there is little to be gained in storing development Lua code in SPIFFS in `lc` compiled format.
- **Flash caching coherency**. The ESP chipset employs hardware enabled caching of the `ICACHE_FLASH` address space, and writing to the flash does not flush this cache. However, in this restart model, the CPU is always restarted before any updates are read programmatically, so this (lack of) coherence isn't an issue.
- **Failsafe reversion**. Since the entire image is precompiled and validated before loading into LFS, the chances of failure during reload are small. The loader uses the Flash NAND rules to write the flash header flag in two parts: one at start of the load and again at the end. If on reboot, the flag in on incostent state, then the LFS is cleared and disabled until the next reload.
......@@ -8,7 +8,7 @@ This FAQ does not aim to help you to learn to program or even how to program in
## What has changed since the first version of this FAQ?
The [NodeMCU company](http://NodeMCU.com/index_en.html) was set up by [Zeroday](zeroday@nodemcu.com) to develop and to market a set of Lua firmware-based development boards which employ the Espressif ESP8266 SoC. The initial development of the firmware was done by Zeroday and a colleague, Vowstar, in-house with the firmware being first open-sourced on Github in late 2014. In mid-2015, Zeroday decided to open the firmware development to a wider group of community developers, so the core group of developers now comprises 6 community developers (including this author), and we are also supported by another dozen or so active contributors, and two NodeMCU originators.
The [NodeMCU company](http://NodeMCU.com/index_en.html) was set up by [Zeroday](mailto:zeroday@nodemcu.com) to develop and to market a set of Lua firmware-based development boards which employ the Espressif ESP8266 SoC. The initial development of the firmware was done by Zeroday and a colleague, Vowstar, in-house with the firmware being first open-sourced on Github in late 2014. In mid-2015, Zeroday decided to open the firmware development to a wider group of community developers, so the core group of developers now comprises 6 community developers (including this author), and we are also supported by another dozen or so active contributors, and two NodeMCU originators.
This larger active team has allowed us to address most of the outstanding issues present at the first version of this FAQ. These include:
......@@ -43,7 +43,7 @@ Whilst the Lua standard distribution includes a stand-alone Lua interpreter, Lua
The ESP8266 was designed and is fabricated in China by [Espressif Systems](http://espressif.com/new-sdk-release/). Espressif have also developed and released a companion software development kit (SDK) to enable developers to build practical IoT applications for the ESP8266. The SDK is made freely available to developers in the form of binary libraries and SDK documentation. However this is in a *closed format*, with no developer access to the source files, so anyone developing ESP8266 applications must rely solely on the SDK API (and the somewhat Spartan SDK API documentation). (Note that for the ESP32, Espressif have moved to an open-source approach for its ESP-IDF.)
The NodeMCU Lua firmware is an ESP8266 application and must therefore be layered over the ESP8266 SDK. However, the hooks and features of Lua enable it to be seamlessly integrated without losing any of the standard Lua language features. The firmware has replaced some standard Lua modules that don't align well with the SDK structure with ESP8266-specific versions. For example, the standard `io` and `os` libraries don't work, but have been largely replaced by the NodeMCU `node` and `file` libraries. The `debug` and `math` libraries have also been omitted to reduce the runtime footprint (`modulo` can be done via `%`, `power` via `^`).
The NodeMCU Lua firmware is an ESP8266 application and must therefore be layered over the ESP8266 SDK. However, the hooks and features of Lua enable it to be seamlessly integrated without losing any of the standard Lua language features. The firmware has replaced some standard Lua modules that don't align well with the SDK structure with ESP8266-specific versions. For example, the standard `io` and `os` libraries don't work, but have been largely replaced by the NodeMCU `node` and `file` libraries. The `debug` and `math` libraries have also been omitted to reduce the runtime footprint (`modulo` can be done via `%`, `power` via `^`). Note that the `io.write()` function described in Lua's [Simple I/O Model](https://www.lua.org/pil/21.1.html) is not replaced by the `file` library. To write to the same serial port that the `print(string)` function uses by default, use `uart.write(0,string)`.
NodeMCU Lua is based on [eLua](http://www.eluaproject.net/overview), a fully featured implementation of Lua 5.1 that has been optimized for embedded system development and execution to provide a scripting framework that can be used to deliver useful applications within the limited RAM and Flash memory resources of embedded processors such as the ESP8266. One of the main changes introduced in the eLua fork is to use read-only tables and constants wherever practical for library modules. On a typical build this approach reduces the RAM footprint by some 20-25KB and this makes a Lua implementation for the ESP8266 feasible. This technique is called LTR and this is documented in detail in an eLua technical paper: [Lua Tiny RAM](http://www.eluaproject.net/doc/master/en_arch_ltr.html).
......
File mode changed from 100755 to 100644
......@@ -144,13 +144,17 @@ print("\nFile system info:\nTotal : "..total.." (k)Bytes\nUsed : "..used.." (k)B
Lists all files in the file system.
#### Syntax
`file.list()`
`file.list([pattern])`
#### Parameters
none
#### Returns
a Lua table which contains the {file name: file size} pairs
a Lua table which contains all {file name: file size} pairs, if no pattern
given. If a pattern is given, only those file names matching the pattern
(interpreted as a traditional [Lua pattern](https://www.lua.org/pil/20.2.html),
not, say, a UNIX shell glob) will be included in the resulting table.
`file.list` will throw any errors encountered during pattern matching.
#### Example
```lua
......
......@@ -224,7 +224,22 @@ Step | Pin 1 | Pin 2 | Duration (&#956;S) | Range | Next Step
When turning this into the table structure as described below, you don't need to specify anything
special when the number of the next step is one more than the current step. When specifying an out of order
step, you must specify how often you want this to be performed. A very large value can be used for roughly infinite.
step, you must specify how often you want this to be performed. The number of iterations can be up to around 4,000,000,000 (actually any value that fits into
an unisgned 32 bit integer). If this isn't enough repeats, then loops can be nested as below:
```
{
{ [1] = gpio.HIGH, [2] = gpio.LOW, delay=500 },
{ [1] = gpio.LOW, [2] = gpio.HIGH, delay=500, loop=1, count=1000000000, min=400, max=600 },
{ loop=1, count=1000000000 }
}
```
The loop/count in step 2 will cause 1,000,000,000 pulses to be output (at 1kHz). This is around 11 days. At this point, it will continue onto step 3 which triggers the
11 days of 1kHz. THis process will repeat for 1,000,000,000 times (which is roughly 30 Million years).
The looping model is that associated with each loop there is a hidden variable which starts at the `count` value and decrements on each iteration until it gets to zero
when it then proceeds to the next step. If control reaches that loop again, then the hidden variable is reset to the value of `count` again.
## gpio.pulse.build
......@@ -243,7 +258,7 @@ Note this that is the NodeMCU pin number and *not* the ESP8266 GPIO number. Mult
set at the same time. Note that any valid GPIO pin can be used, including pin 0.
- `delay` specifies the number of microseconds after setting the pin values to wait until moving to the next state. The actual delay may be longer than this value depending on whether interrupts are enabled at the end time. The maximum value is 64,000,000 -- i.e. a bit more than a minute.
- `min` and `max` can be used to specify (along with `delay`) that this time can be varied. If one time interval overruns, then the extra time will be deducted from a time period which has a `min` or `max` specified. The actual time can also be adjusted with the `:adjust` API below.
- `count` and `loop` allow simple looping. When a state with `count` and `loop` is completed, the next state is at `loop` (provided that `count` has not decremented to zero). The first state is state 1. The `loop` is rather like a goto instruction as it specifies the next instruction to be executed.
- `count` and `loop` allow simple looping. When a state with `count` and `loop` is completed, the next state is at `loop` (provided that `count` has not decremented to zero). The count is implemented as an unsigned 32 bit integer -- i.e. it has a range up to around 4,000,000,000. The first state is state 1. The `loop` is rather like a goto instruction as it specifies the next instruction to be executed.
#### Returns
`gpio.pulse` object.
......@@ -383,7 +398,7 @@ pulser:adjust(177)
## gpio.pulse:update
This can change the contents of a particular step in the output program. This can be used to adjust the delay times, or even the pin changes. This cannot
be used to remove entries or add new entries.
be used to remove entries or add new entries. Changing the `count` will change the initial value, but not change the current decrementing value;
#### Syntax
`pulser:update(entrynum, entrytable)`
......@@ -396,7 +411,7 @@ be used to remove entries or add new entries.
Nothing
Example
#### Example
```lua
pulser:update(1, { delay=1000 })
```
......
......@@ -3,7 +3,11 @@
| :----- | :-------------------- | :---------- | :------ |
| 2016-02-24 | [Philip Gladstone](https://github.com/pjsg) | [Philip Gladstone](https://github.com/pjsg) | [mdns.c](../../../app/modules/mdns.c)|
[Multicast DNS](https://en.wikipedia.org/wiki/Multicast_DNS) is used as part of Bonjour / Zeroconf. This allows system to identify themselves and the services that they provide on a local area network. Clients are then able to discover these systems and connect to them.
[Multicast DNS](https://en.wikipedia.org/wiki/Multicast_DNS) is used as part of Bonjour / Zeroconf. This allows systems to identify themselves and the services that they provide on a local area network. Clients are then able to discover these systems and connect to them.
!!! note
This is a mDNS *server* module. If you are looking for a mDNS *client* for NodeMCU (i.e. to query mDNS) then [udaygin/nodemcu-mdns-client](https://github.com/udaygin/nodemcu-mdns-client) may be an option.
## mdns.register()
Register a hostname and start the mDNS service. If the service is already running, then it will be restarted with the new parameters.
......@@ -15,7 +19,7 @@ Register a hostname and start the mDNS service. If the service is already runnin
- `hostname` The hostname for this device. Alphanumeric characters are best.
- `attributes` A optional table of options. The keys must all be strings.
The `attributes` contains two sorts of attributes -- those with specific names, and those that are service specific. [RFC 6763](https://tools.ietf.org/html/rfc6763#page-13)
The `attributes` contains two sorts of attributes those with specific names, and those that are service specific. [RFC 6763](https://tools.ietf.org/html/rfc6763#page-13)
defines how extra, service specific, attributes are encoded into the DNS. One example is that if the device supports printing, then the queue name can
be specified as an additional attribute. This module supports up to 10 such attributes.
......@@ -35,7 +39,7 @@ Various errors can be generated during argument validation. The NodeMCU must hav
mdns.register("fishtank", {hardware='NodeMCU'})
Using `dns-sd` on OS X, you can see `fishtank.local` as providing the `_http._tcp` service. You can also browse directly to `fishtank.local`. In Safari you can get all the mDNS web pages as part of your bookmarks menu.
Using `dns-sd` on macOS, you can see `fishtank.local` as providing the `_http._tcp` service. You can also browse directly to `fishtank.local`. In Safari you can get all the mDNS web pages as part of your bookmarks menu.
mdns.register("fishtank", { description="Top Fishtank", service="http", port=80, location='Living Room' })
......
......@@ -172,6 +172,40 @@ none
#### Returns
flash ID (number)
## node.flashindex()
Returns the function reference for a function in the [LFS (Lua Flash Store)](../lfs.md).
#### Syntax
`node.flashindex(modulename)`
#### Parameters
`modulename` The name of the module to be loaded. If this is `nil` or invalid then an info list is returned
#### Returns
- In the case where the LFS in not loaded, `node.flashindex` evaluates to `nil`, followed by the flash and mapped base addresss of the LFS
- If the LFS is loaded and the function is called with the name of a valid module in the LFS, then the function is returned in the same way the `load()` and the other Lua load functions do.
- Otherwise an extended info list is returned: the Unix time of the LFS build, the flash and mapped base addresses of the LFS and its current length, and an array of the valid module names in the LFS.
#### Example
The `node.flashindex()` is a low level API call that is normally wrapped using standard Lua code to present a simpler application API. See the module `_init.lua` in the `lua_examples/lfs` directory for an example of how to do this.
## node.flashreload()
Reload the [LFS (Lua Flash Store)](../lfs.md) with the flash image provided. Flash images are generated on the host machine using the `luac.cross`commnad.
#### Syntax
`node.flashreload(imageName)`
#### Parameters
`imageName` The of name of a image file in the filesystem to be loaded into the LFS.
#### Returns
If the LFS image has the incorrect signature or size, then `false` is returned.
In the case of the `imagename` being a valid LFS image, this is then loaded into flash. The ESP is then immediately rebooted so control is not returned to the calling application.
## node.flashsize()
Returns the flash chip size in bytes. On 4MB modules like ESP-12 the return value is 4194304 = 4096KB.
......@@ -221,7 +255,7 @@ system heap size left in bytes (number)
## node.info()
Returns NodeMCU version, chipid, flashid, flash size, flash mode, flash speed.
Returns NodeMCU version, chipid, flashid, flash size, flash mode, flash speed, and Lua File Store (LFS) usage statics.
#### Syntax
`node.info()`
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment